Download the PHP package codemonster-ru/annabel without Composer

[!IMPORTANT] This repository is read-only.

Development happens in the Annabel monorepo: https://github.com/codemonster-ru/annabel

Issues and pull requests should be opened there.

Annabel

Elegant and lightweight PHP framework for modern web applications.

Installation

Quick Start

CLI

Annabel ships with a lightweight CLI similar to Laravel's artisan. It already supports:

• about - show version, base path, and loaded providers
• route:list - list registered routes
• config:get key - read a config value
• config:list - list config values with secrets redacted
• container:list - show container bindings/instances
• vendor:publish - publish package config, migrations, views, or assets
• serve - run PHP built-in server (default 127.0.0.1:8000)
• make:controller, make:model, make:middleware, make:request, make:policy - generate application classes
• With codemonster-ru/database installed: make:migration, migrate, migrate:rollback, migrate:status, make:seed, seed (appear in annabel list; connection is checked when commands run)

Commands may be registered by service providers and are resolved through the application container, including constructor dependency injection:

New commands may implement execute(InputInterface $input, OutputInterface $output): int. ArgvInput provides positional arguments and parsed long options; commands return ExitCode constants. The legacy handle(array) method remains supported for existing commands.

Testing

Application tests can use Annabel's lightweight HTTP helpers:

Database Integration

Annabel ships with first-class integration for
codemonster-ru/database.

1. Create config/database.php

2. Usage

Helpers

All helpers are autoloaded automatically.

Filesystem

Annabel registers codemonster-ru/filesystem by default. Publish the default config and use storage() to read or write files:

HTTP Client

Annabel registers codemonster-ru/http-client by default. Configure defaults in config/http-client.php and use http_client() for external API calls:

Middleware

Annabel supports PSR-15 middleware via Psr\Http\Server\MiddlewareInterface. Route middleware may be registered by class name, and global middleware may be added to the kernel with addMiddleware().

Middleware aliases and groups keep routes compact:

The framework registers auth and can when auth is enabled. The security provider registers csrf, throttle, and the default web / api groups. Custom aliases and groups can be registered on the HTTP kernel:

Publish the security config to tune CSRF, rate-limit storage, trusted proxies, and named throttle presets:

Authentication

Annabel registers codemonster-ru/auth by default. Publish the default config and configure a user provider in config/auth.php, or provide a small in-memory list for local applications:

Production applications should bind a database-backed Codemonster\Auth\Contracts\UserProviderInterface implementation through auth.provider.

Routing

Routes support dynamic parameters, constraints, names, and URI generation:

Route parameters are injected into closures and controllers by parameter name. The current Codemonster\Http\Request may be type-hinted alongside route parameters.

API Resources

API resources provide one transformation for individual models, collections, and existing simplePaginate() results:

Logging

Annabel binds Psr\Log\LoggerInterface in the container. Configure the default channel in config/logging.php; unhandled HTTP exceptions are reported before the error response is rendered.

Cache

Annabel binds Psr\SimpleCache\CacheInterface in the container. Configure the default store in config/cache.php; the framework ships with array, file, and redis stores. Set CACHE_STORE=redis and configure REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, and REDIS_CACHE_DB for shared cache in multi-instance deployments.

Mail

Annabel registers codemonster-ru/mail by default. Configure the default mailer in config/mail.php; the framework ships with array, log, sendmail, and Symfony-powered smtp transports. Set MAIL_MAILER=smtp and provide an SMTP DSN through MAILER_DSN.

Queue

Annabel registers codemonster-ru/queue by default. Configure the default connection in config/queue.php; the framework ships with sync, database, and redis drivers.

The default sync connection runs jobs immediately. For SQL-backed background jobs, set QUEUE_CONNECTION=database, publish queue migrations, run migrate, and start the worker:

For Redis-backed workers, set QUEUE_CONNECTION=redis and configure REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, REDIS_QUEUE_DB, and QUEUE_REDIS_PREFIX. Redis failed jobs are stored in Redis and work with the same queue:failed, queue:retry, and queue:flush commands.

Scheduler

Annabel registers codemonster-ru/scheduler by default. Define tasks in routes/schedule.php and run schedule:run every minute from cron:

Use schedule:list to inspect registered tasks, cron expressions, due status, and overlap locks.

Scheduler locks use the configured cache store when the cache provider is registered.

Production optimization

Build configuration and route caches during deployment:

Routes with closures cannot be cached. Use controller handlers such as [HomeController::class, 'index']. Clear all generated caches before changing environment configuration or when troubleshooting:

The individual config:cache, config:clear, route:cache, and route:clear commands are also available.

Events

Annabel binds Psr\EventDispatcher\EventDispatcherInterface and Psr\EventDispatcher\ListenerProviderInterface. Register listeners through the framework listener provider and dispatch events through the PSR dispatcher.

Validation

Annabel ships with a small validation layer for request/config data. It supports common scalar rules, nested fields through dot notation, validated() data, and validateOrFail() for exception-driven flows.

Controllers can use Codemonster\Annabel\Http\ValidatesRequests to validate the current request. Validation failures return JSON 422 responses for API requests, or redirect back with flashed errors and _old_input for web forms. Redirects are restricted to local same-origin locations. Sensitive fields are excluded recursively according to config/validation.php.

HTTP Exceptions

Framework HTTP exceptions live under Codemonster\Annabel\Http\Exceptions. They expose stable status and header contracts for bad requests, authentication, authorization, missing routes, and unsupported methods.

Container parameters

The Annabel container implements Psr\Container\ContainerInterface, so it can be passed to libraries expecting a PSR-11 container.

You can pass named constructor parameters when resolving classes or closure bindings:

Note: for singleton bindings, passing parameters after the instance is resolved throws an exception.

Note: Application::serve() will throw if an instance already exists; call Application::resetInstance() first.

Providers

Annabel reads provider settings from config/app.php before registering services.

All providers are registered first and booted after registration completes.

Installed packages may declare providers in Composer metadata:

Only providers owned by that package should be declared. Applications can disable selected packages through providers.packages.dont_discover, use * to disable all package discovery, or set providers.packages.discover to false. The generated manifest cache is invalidated when package composer.json metadata changes.

Publishable Resources

Package providers may register publishable files or directory trees:

Publishing is explicit and does not overwrite existing files unless requested:

Destinations must remain inside the application base path. Symbolic-link escape paths are rejected.

Testing

Author

Kirill Kolesnikov

License

MIT