Phred/README.md

Phred

A PHP MVC framework:

• Intended for projects of all sizes, and solo or team development.
  • The single router call per controller style makes it easy for teamwork without stepping on each others toes.
• REQUIREMENTS
  • PHP 8.1+
  • Primarily meant for Apache/Nginx webservers, will look into supporting other webservers in the future.
• PSR-4 autoloading.
• Installed through Composer (composer create-project getphred/phred)
• Environment variables (.env) for configuration.
• Supports two API formats
  • pragmatic REST (default)
  • JSON:API
  • Choose via .env:
    • API_FORMAT=rest (plain JSON responses, RFC7807 error format.)
    • API_FORMAT=jsonapi (JSON:API compliant documents and error objects.)
    • You may also negotiate per request using the Accept header.
• TESTING environment variables (.env)
  • TEST_RUNNER=codeception
  • TEST_PATH=tests
    • TEST_PATH is relative to both project root and each module root.
• Dependency Injection
• Fully Pluggable, but ships with defaults:
  • Pluggability model
    • Core depends on Phred contracts (Phred\Contracts\*) and PSRs
    • Concrete implementations are provided by Service Providers.
    • Swap packages by changing .env and enabling a provider.
  • Driver keys (examples)
    • ORM_DRIVER=pairity|doctrine
    • TEMPLATE_DRIVER=eyrie|twig|plates
    • FLAGS_DRIVER=flagpole|unleash
    • TEST_RUNNER=codeception
  • Primary contracts
    • Template\RendererInterface
    • Orm\EntityManagerInterface (or repositories)
    • Flags\FeatureFlagClientInterface
    • Testing\TestRunnerInterface.
  • Default Plug-ins
    • Feature Flags through getphred/flagpole
    • ORM through getphred/pairity (handles migrations, seeds, and db access)
    • Unit Testing through codeception/codeception
      • Testing is provided as a CLI dev capability only; it is not part of the HTTP request lifecycle.
    • Template Engine through getphred/eyrie
• Other dependencies:
  • Dependency Injection through php-di/php-di
  • Static Analysis through phpstan/phpstan
  • Code Style Enforcement through friendsofphp/php-cs-fixer
  • Logging through monolog/monolog
  • Config and environment handling through vlucas/phpdotenv
  • HTTP client through guzzlehttp/guzzle
• CONTROLLERS
  • Invokable controllers (Actions),
    • Single router call per controller,
    • public function __invoke(Request $request) method entry point on controller class,
• VIEWS
  • Classes for data manipulation/preparation before rendering Templates,
    • $this->render(<template_name>, <data_array>); to render a template.
• SERVICES
  • for business logic.
• SERVICE PROVIDERS
  • for dependency injection.
• MIGRATIONS
  • for database changes.
• Modular separation, similar to Django apps.
  • Nested Models
  • Nested Controllers
  • Nested Views
  • Nested Services
  • Nested Migrations
  • Nested Service Providers
  • Nested Routes
  • Nested Templates
  • Nested Tests
• CLI Helper called phred
  • php phred create:command <name> // Creates a CLI command under `console/commands
  • php phred create:module <name> // Creates a module
  • php phred create:<module>:controller // Creates a controller in the specified module
  • php phred create:<module>:model // Creates a model in the specified module
  • php phred create:<module>:migration // Creates a migration in the specified module
  • php phred create:<module>:seed // Creates a seeder in the specified module
  • php phred create:<module>:test // Creates a test in the specified module
  • php phred create:<module>:view / Creates a view in the specified module
  • php phred db:backup // Backup the database
  • php phred db:restore -f <db_backup_file> // Restore the database from the specified backup file
  • php phred migrate [-m <module>] // Migrate entire project or module
  • php phred migration:rollback [-m <module>] // Rollback entire project or module
  • php phred seed
  • php phred seed:rollback
  • php phred test[:<module>] // Test entire project or module
    • Runs tests using the configured test runner (dev only).
    • Requires require-dev dependencies.
  • php phred run [-p <port>]
    • Spawns a local PHP webserver on port 8000 (unless specified otherwise using -p)
• CLI Helper is extendable through CLI Commands.

Command discovery

• Core commands (bundled with Phred) are discovered from src/commands.
• User/project commands are discovered from console/commands in your project root.

Run the CLI:

php phred list

Add your own command by creating a PHP file under console/commands, returning an instance of Phred\Console\Command (or an anonymous class extending it).

(Or by running php phred create:command <name>)

Example:

<?php
use Phred\Console\Command;
use Symfony\Component\Console\Input\InputInterface as Input;
use Symfony\Component\Console\Output\OutputInterface as Output;

return new class extends Command {
    protected string $command = 'hello:world';
    protected string $description = 'Example user command';
    public function handle(Input $in, Output $out): int { $out->writeln('Hello!'); return 0; }
};