README

Lightweight API-REST framework based on PHP Object Foundation. It provides controllers, session authentication, and an extensible user model while delegating persistence to plugins.

Core features

• Session and CRUD controllers.
• Extensible user model (User, OwnerUser, ApiUser, AdminUser).
• Repository abstraction via interfaces (IUserRepository, IPInfoCacheRepository).
• Repository bootstrap via RepositoryProvider.

Plugin system The core has no database dependency. Plugins provide concrete repository implementations and register the driver.

Available plugins:

• php-foundation-api-rest-mongodb
• php-foundation-api-rest-sqlite

Each plugin provides:

• Implementations of IUserRepository and IPInfoCacheRepository.
• A RepositoryBootstrap that registers repositories via RepositoryProvider::set(...).

Installation

Install the core and the plugin you need:

composer require beecubu/php-foundation-api-rest
composer require beecubu/php-foundation-api-rest-mongodb
# or
composer require beecubu/php-foundation-api-rest-sqlite

Technical configuration

1) Initialize repositories

MongoDB

use Beecubu\Foundation\ApiRest\MongoDB\RepositoryBootstrap;

RepositoryBootstrap::init();

SQLite

use Beecubu\Foundation\ApiRest\SQLite\RepositoryBootstrap;

RepositoryBootstrap::init();

If you want to inject custom repositories:

use Beecubu\Foundation\ApiRest\Core\Persistence\RepositoryProvider;
use Beecubu\Foundation\ApiRest\SQLite\Core\Persistence\UserDB;
use Beecubu\Foundation\ApiRest\SQLite\Core\Persistence\IPInfoCacheDB;

RepositoryProvider::set(UserDB::current(), IPInfoCacheDB::current());

2) Driver configuration

Each plugin has its own driver configuration:

MongoDB

• Configure the MongoDB connection (URI, database, etc).
• Review your project bootstrap where the connection is created.

SQLite

• Ensure the SQLite file is accessible and writable.
• The driver creates tables on demand.

3) HTTP error status codes

By default, API errors return proper HTTP 4xx/5xx status codes.

If you need to preserve the legacy behavior and keep returning HTTP 200 for errors, disable it explicitly:

define('RESPONSE_USE_HTTP_ERROR_CODES', false);

When this flag is enabled, successful responses keep their usual codes and error responses return the status code declared by each public exception.

4) Request helpers

Use Request::current() to read request body data, options, files, and query params:

use Beecubu\Foundation\ApiRest\Api\Entities\Request\Request;

$request = Request::current();

$email = $request->getDataValue('email');
$confirmed = $request->getOption('confirm', false);
$query = $request->getQueryParams();
$search = $request->getQueryParam('search');
$filter = $request->getQueryParamsAs(MyFilter::class);
$file = $request->getFile('avatar');

getDataAs() and getQueryParamsAs() require a class that extends Beecubu\Foundation\Core\Serializable.

5) User entities

To customize the user model, create a class that extends ApiUser (or User) and use it where needed.

Basic example:

use Beecubu\Foundation\ApiRest\Core\Entities\Users\ApiUser;

class MyApiUser extends ApiUser
{
    // Add your own fields or logic
}

6) Session and authentication

Session endpoints work with ApiUser. The session controller resolves the user via the configured repository.

JWT + secure double-cookie Sessions are persisted as JWTs split across two cookies for extra safety:

• Cookie 1 stores the public part (header.payload) and is readable by JS.
• Cookie 2 stores the signature only and is HttpOnly.

Both cookies are marked Secure in live mode, scoped to the current subdomain, and share the same expiry.
On each successful login or session refresh, a new JWT is generated and both cookies are updated.
If either cookie is missing or the JWT fails validation, the session is treated as invalid and no user is loaded.

Notes

• The core does not require any database.
• Repository implementations live-in plugins.
• The same API code can run on MongoDB or SQLite by swapping the plugin.