orbiter/satellite-app

Easy to use Event & Middleware Mini-Framework, powered by popular projects and PSR's

0.4.2 2022-10-27 17:43 UTC

README



                       ๐ŸŒ
                     ๐Ÿ›ฐ๏ธ
                   ยท          
                ยท 
     ๐Ÿ›ฐ๏ธ๐Ÿ›ฐ๏ธ๏ธ   ยท
    ๐Ÿ›ฐ๏ธ๐ŸŒ๐Ÿ›ฐ๏ธ   ยท  ยท  ยท ๐Ÿ›ฐ๏ธ๐ŸŒ
     ๐Ÿ›ฐ๏ธ๐Ÿ›ฐ๏ธ๏ธ

 

Easy to use Event & Middleware Framework, powered by popular micro-libraries and based on PSRs.

Supports PHP 8.1+ and composer

TL;DR

Quick-Jump into develop:

composer create-project orbiter/satellite-app ./satellite

cd ./satellite

# create `.env` file, 
# add for local-dev: `env=local`
touch .env 

# start PHP Dev Server
cd web && php -S localhost:3333 ./index.php display_errors=0

# or point the Apache Root to `/web/`
# or point the NGINX entry to `/web/index.php`
# or use Docker: `docker-compose up`

Open your browser on: http://localhost:3333

Look into files:

  • config folder with app config and wiring
  • assemble.php composer autoload, gathers configurations and creates the system modules from that config
  • launch.php runs assemble() and dispatches the SatelliteApp event
  • app folder with a basic commands and route handler structure

Setup

Install app skeleton and dependencies with composer in folder satellite:

# with composer installed on machine:
composer create-project orbiter/satellite-app satellite

# with composer and docker on windows:
docker run -it --rm -v %cd%/satellite:/app composer create-project orbiter/satellite-app .
docker run -it --rm -v %cd%/satellite:/app composer create-project --stability=dev orbiter/satellite-app:dev-master .

# with composer and docker on unix:
docker run -it --rm -v `pwd`/satellite:/app composer create-project orbiter/satellite-app .
docker run -it --rm -v `pwd`/satellite:/app composer create-project --stability=dev orbiter/satellite-app:dev-master .

# go into project folder:
cd ./satellite

Run with:

Linux, PHP Dev Server

Setup correct user rights, then start and open http://localhost:3333

chmod +x start.sh

./start.sh

PHP Command-Line

Execute defined commands.

php cli <command> <..attr> <..b>

Docker, docker-compose

Includes configurable PHP Dockerfile with:

  • PHP 8.1
    • with FPM and a few extensions
    • reusing FPM for a clean CLI worker image
  • OPCache
  • PostgreSQL Client libs (using pdo)
  • NGINX base image for local routing
  • customize in Dockerfile
  • a more "production" ready image, preconfigured for building in CI with docker-compose--prod.yml

For docker image configs see files in _docker and _nginx.

Start containers specified in docker-compose.yml, then open: http://localhost:3333

docker-compose up

# open shell in app container
docker-compose exec app sh

# run command in temporary worker container
docker-compose run --rm worker php cli demo

# run extra composer container on windows:
docker run -it --rm -v %cd%:/app composer dumpautoload
# run extra composer container on unix:
docker run -it --rm -v `pwd`:/app composer dumpautoload

# run tests with temporary `app` container:
docker-compose run -T --rm app sh -c "cd /var/www/html && ./vendor/bin/phpunit --testdox tests"

# running tests with a temporary `phpunit` in a prebuild container:
docker run -i --rm bemiteu/satellite-app:master sh -c "cd /var/www && wget -O phpunit https://phar.phpunit.de/phpunit-9.phar && chmod +x phpunit && cd html && /var/www/phpunit --testdox tests"

Web-Server

On a web-server the web/index.php file serves as public entry point.

Apache: point server/vhost root to /web and use the included .htaccess

NGINX: example files in _nginx.

Config

Use e.g. .env to add configuration.

Default's config includes:

  • env var env: if in production or not in production
    • with value prod it is assumed in the App (not the framework) that it is in production
    • use $_ENV['env'] === 'prod' to check for production
    • for dev-error pages: add var dev.editor with one value of PrettyPageHandler::EDITOR_* to link whoops "open file" with IDE
  • /config/config.php - main config
    • configures which other config files are included
    • aggregates and caches the config for production usage
  • /config/dependencies.php - definitions for PHP-DI
  • /config/events.php - define app components flow
  • /config/pipeline.php - setup PSR middlewares and pipeline

PSRs

This app serves as mini-framework, with PSR powered libraries, ready-to-use Annotations and not much more.

It is build upon PSRs and popular, specialized packages implementing them or other great stuff.

  • PSR-3 - Logger
  • PSR-4 - autoload classes and forget require_once
  • PSR-1,12 - Code Style Guides
    • except brackets location rule: same-line instead of next-line for opening {
  • PSR-6 - Cache
  • PSR-7 - HTTP Message
    • ๐Ÿ“ฆ nyholm\psr7
    • request and response data definitions
    • used further by PSR-15, PSR-17 and PSR-18
  • PSR-11 - Container for InterOp
    • ๐Ÿ“ฆ php-di/php-di
    • service container for ease and modularity
    • dependency injection with @Annotations, @var PHPDoc and Reflection support
  • PSR-14 - Event Dispatcher and Listener
    • ๐Ÿ“ฆ orbiter/satellite
    • as the core of how things are put together
  • PSR-15 - HTTP Handlers
    • ๐Ÿ“ฆ orbiter/satellite-response
    • handle route requests with a powerful middleware pipeline
  • PSR-16 - Simple Cache
  • PSR-17 - HTTP Factories
    • ๐Ÿ“ฆ nyholm\psr7
    • context about request
    • for request & response initiations
  • PSR-18 - HTTP Client

๐Ÿ“ฆ = included in satellite-app template

Packages

  • orbiter/satellite Latest Stable Version
    • implements PSR-14 Event Dispatcher and Listener
    • with invoker to execute anything, PSR-11 compatible
    • optional event-handler based profiling
    • see package repository
  • orbiter/satellite-console Latest Stable Version
  • orbiter/satellite-response Latest Stable Version
    • middleware pipe execution
    • implements PSR-15 through equip/dispatch, PSR-11 compliant
    • implements PSR-7,17 through nyholm/psr7 and nyholm/psr7-server
    • with simple emitter by narrowspark/http-emitter
    • see package repository
  • orbiter/satellite-route Latest Stable Version
  • orbiter/annotations-util Latest Stable Version
    • annotations by doctrine/annotations with cached reflections
    • get classes, methods and properties which are annotated
    • see AnnotationsUtil
  • orbiter/satellite-whoops Latest Stable Version
    • Whoops error display for CLI and Routes
    • only when $_ENV['env'] not prod (configurable in assemble.php)
  • orbiter/satellite-config Latest Stable Version
  • orbiter/satellite-launch Latest Stable Version
  • orbiter/satellite-system Latest Stable Version
    • system setup and core wire-up, e.g. from $config to a cached PSR container
    • see package repository

A lot of work for APIs is done by PSR-15 HTTP Middleware, find more awesome middlewares.

Download Build

There is no downloadable version - see Setup on how to install with composer.

We use composer as package manager, like in any modern PHP project.

Feel free to reach out for a training request.

License

This project is free software distributed under the MIT License.

Contributors

By committing your code to the code repository you agree to release the code under the MIT License attached to the repository.

Maintained by Michael Becker