Skip to content

Directory structure

The directory structure of the eQual framework is designed for simplicity and efficiency, providing a clear organization that enhances the development process.

Root directory structure

/
├── bin
├── lib
├── packages
├── public
│   ├── .htaccess
│   └── index.php
├── spool
├── eq.lib.php
└── run.php
FILE DESCRIPTION
eq.lib.php Bootstrap library. Defines constants and global utilities.
run.php Server script for client-server mode.
lib Folder containing the eQual library (mostly classes and services definitions).
packages Folder containing installed packages (class definitions, translations, views, actions, etc.).
public Root public folder for the web server.
bin Folder containing values of binary fields (see BINARY_STORAGE_DIR).
spool Dedicated to email sending.

The root folder is also the place to include a composer.json file and the subsequent /vendor directory for managing dependencies.

lib

The lib directory contains libraries and services used as external resources. These are core utilities and components that are shared across the framework. Examples include:

  • Core services: Utilities for file manipulation, database interaction, and other low-level operations.

  • Shared classes: Common classes used across multiple packages or modules.

  • Framework utilities: Helper functions and classes that provide additional functionality to the framework.

packages

The packages directory is the heart of the framework, containing all installed packages. Each package typically includes:

  • Actions: Controllers and logic for handling specific tasks or API endpoints.

  • Views: Templates and rendering logic for the user interface.

  • Translations: Language files for internationalization.

  • Configurations: Package-specific settings and initialization files.

  • Tests: Unit tests for ensuring the package's functionality.

Packages are modular and can be added, removed, or updated independently, making the framework highly extensible.

public

The public directory is the root folder for the web server. It contains files that are directly accessible by the client, such as:

  • .htaccess: Configuration file for Apache servers to manage URL rewriting, access control, and other server settings.

  • index.php: The main entry point for handling HTTP requests and routing them to the appropriate controllers.

This directory is where static assets (e.g., JavaScript, CSS, images) should be placed for client-side use.

bin

The bin directory is used to store binary data, such as files uploaded by users or generated by the application. It is referenced by the BINARY_STORAGE_DIR constant in the framework configuration.

spool

The spool directory is dedicated to email sending. It acts as a temporary storage area for emails that are queued for delivery. The framework processes these emails asynchronously to improve performance and reliability.

Built-in Services

eQual provides several built-in services to handle common tasks such as authentication, routing, and object management. Below is a list of these services and their descriptions:

ID DESCRIPTION
report equal\error\Reporter
Handles error reporting and logging.
auth equal\auth\AuthenticationManager
Manages credentials and tokens.
access equal\access\AccessController
Manages user and group permissions.
context equal\php\Context
Handles HTTP requests and responses.
validate equal\data\DataValidator
Validates entity and controller fields.
adapt equal\data\DataAdapterProvider
Transforms data into specific formats.
orm equal\orm\ObjectManager
Manages ORM objects.
route equal\route\Router
Handles routing.
spool equal\email\EmailSpooler
Manages email spooling.

Orm Service

The orm service can be accessed without a database connection, unlike the auth service, which requires user objects.

Custom Services

In some cases, it may be necessary to design custom services with specific logic. These services can replace default services by using the same predefined name in the service container.

For example, to override the AccessController:

list($params, $providers) = eQual::announce([
    'response' => [
        'content-type' => 'application/json',
        'charset' => 'utf-8',
        'accept-origin' => '*'
    ],
    'providers' => [
        'auth',
        'access' => custom\AccessController
    ]
]);

Custom services can also be defined in the config.inc.php file of a package to provide package-specific functionality.

Additional Notes

  • Composer Integration: The framework supports Composer for dependency management. Place a composer.json file in the root directory to define dependencies, and the /vendor directory will be created to store them.

  • Extensibility: The modular design of the packages directory allows developers to create and integrate new features without modifying the core framework.

  • Public Access: Only the public directory should be exposed to the web server. All other directories should remain inaccessible for security reasons.

Advanced Debugging Techniques

  • Trace CRUD operations:
    The ObjectManager handles all object lifecycle operations. To trace issues:

    • Use validate() to check field constraints and unique values.
    • Use read(), create(), update(), and delete() to trace object state changes.
    • Enable debug output by setting DEBUG_MODE and DEBUG_LEVEL in your config.

  • Workflow & transitions:
    Use transition() and canTransition() to debug workflow state changes and constraints.

  • Auto-loading & class resolution:
    If a class isn’t loading, check getStaticInstance() and getObjectClassFile() for autoload logic.

  • Trace permission checks:
    Use hasRight(), isAllowed(), and getUserRights() to debug access control logic.

    • Check how rights are resolved for users and groups.
    • Use getUserRoles() and hasRole() for RBAC debugging.
    • Policies are checked via isCompliant() and canPerform().

  • Debugging policies:
    Policies are defined in model classes and invoked via reflection. If a policy fails, check the error output from isCompliant().

Custom Debugging Tools

Extending Debugging

  • Custom error reporting:
    Extend equal\error\Reporter or add hooks in equal\log\Logger for custom log formats or destinations.

  • Override built-in services:
    You can override services like AccessController by injecting your own class in controllers: 

    // filepath: /var/www/html/equal/doc/community/internal-architecture/framework-internals.md
list($params, $providers) = eQual::announce([
    'providers' => [
        'auth',
        'access' => custom\AccessController
    ]
]);

  • Custom debug console:
    Add new endpoints or UI panels to visualize logs, permissions, or workflow states. Use the console.php app for log viewing.

Domains: Internal Architecture

The equal/orm/Domain.class.php class is central to how the eQual framework handles filtering, searching, and conditional logic on obkects.

A domain is a structured array that defines filter criteria for objects, used in searches, permissions, view visibility, and more. Domains are composed of clauses and conditions. More on that in the Domain documentation.

  • Filtering: Used in ORM searches, views and widgets to filter objects.
  • Visibility: Controls UI element visibility based on object/user context.
  • Permissions: Used in ACLs and policies to deifine when certain rights or action apply.
  • Extensibility: Sup^ports references to dynamic values making domains context-aware.