ricardoper / micra
CLI framework for your apps with a minimum overhead based on Symfony Components
Requires
- php: ^7.2.5
- pimple/pimple: ^3.3
- psr/log: ^1.1
- symfony/console: ^5.0
- symfony/var-dumper: ^5.0
- vlucas/phpdotenv: ^4.1
This package is auto-updated.
Last update: 2024-11-25 21:03:03 UTC
README
Micra is a CLI framework for your apps with a minimum overhead based on Symfony Components.
- PHP >= 7.2
- Customizable with an easy configuration:
- Models
- Commands
- Handlers
- Configurations
- Service Providers
- Error Handler
- Shutdown Handler
- PSR-3 Logger
- Global Helpers
- Better & More Verbose Error Handler
- Environment variables with PHP dotenv
- Pimple Dependency Injection Container
- Medoo Database Framework (MySQL, PostgreSQL, SQLite, MS SQL Server, ...)
Table of Contents
- How to Install
- Most Relevant Folders
- Global Helpers
- Configurations
- Commands
- Run Commands
- Models
- Services Providers
- Handlers
- Database Support
- Exceptions
- Logging
- Benchmarks
How to Install
Run this command from the directory in which you want to install your new Micra Framework.
composer create-project ricardoper/micra [my-app-name]
NOTE:
- Replace
[my-app-name]
with the desired directory name for your new application. - Ensure
storage/
is web writeable.
Most Relevant Folders
- /app : Application code (App Namespace - PSR-4)
- ./Commands : The start point of your tasks. Add your Controllers here.
- ./Handlers : Handles specified behaviors of the application. Add your Handlers here.
- ./Models : Manages the data, logic and rules of the application. Add your Models here.
- ./Services : Define bindings and inject dependencies. Add your Service Providers here.
- /configs : Add/modify your Configurations here
Global Helpers
env(string $variable, string $default)
- Returns environment variables (using DotEnv)app()
- Returns App instancecontainer(string $name)
- Returns Container registered dataconfigs(string $variable, string $default)
- Returns Configuration database_path(string $path)
- Returns base path locationapp_path(string $path)
- Returns app path locationconfigs_path(string $path)
- Returns configs path locationstorage_path(string $path)
- Returns storage path location
Global Helpers for Development Only
dump($var1, $var2, ...)
- Dump varsdd($var1, $var2, ...)
- Dump & die vars
Configurations
You can add as many configurations files as you want (/configs
). These files will be automatically preload and merged in the container based on selected environment.
If you have an environment called "sandbox" and you want to overwrite some configuration only for this environment, you need to create a subfolder "sandbox" in /configs
. Something like that /configs/sandbox
. Then create the file that includes the configuration that you need to replace and the respective keys and values inside it.
/configs/logger.php
return [ 'name' => 'app', 'maxFiles' => 7, ];
/configs/local/logger.php
return [ 'name' => 'app-local', ];
Results of name
for the environment:
- prod : 'app'
- sandbox : 'app'
- local : 'app-local'
- testing : 'app'
NOTE: You can see the example in this framework for the local environment.
Configurations Dot Notation
You can use dot notation to get values from configurations.
/configs/example.php
return [ 'types' => [ 'mysql' => [ 'host' => 'localhost', 'port' => '3306', ], 'postgre' => [ 'host' => 'localhost', 'port' => '3306', ], ], ];
If you want the host
value for MySQL type:
$this->getConfigs('example.types.mysql.host') => 'localhost' configs('example.types.mysql.host') => 'localhost' container('configs')->get('example.types.mysql.host') => 'localhost'
Commands
The start point of your tasks.
You can add as many Commands as you want in a cleaning way (/app/Commands
).
After add your Command, you can enable or disable it in config/[env/]commands.php
configuration file.
NOTE: To have helpers you must extend the Commands with ControllerAbstract located in \App\Kernel\Abstracts
.
use App\Kernel\Abstracts\CommandAbstract; use Symfony\Component\Console\Input\InputInterface; use Symfony\Component\Console\Output\OutputInterface; class HelloCommand extends CommandAbstract { /** * Command name * * @var string */ protected $cmdName = 'Hello'; /** * Configure/explain command */ protected function configure() { $this ->setName($this->cmdName) ->setDescription('Hello World!'); } /** * Execute command process * * @param InputInterface $input * @param OutputInterface $output * @return int */ protected function execute(InputInterface $input, OutputInterface $output): int { $output->writeln('Hello World!'); return 0; } }
Enable it in config/[env/]commands.php
:
use App\Commands\Demo\HelloCommand; return [ 'hello' => HelloCommand::class, ];
Commands Helpers
getApp()
- Returns App objectgetContainer(string $name)
- Returns the App ContainergetConfigs(string $name)
- Returns App ConfigsgetService(string $service)
- Returns Service Provider from container by name
Inbuilt commands
- Deps : Is an in-built command to see if your system respect all the dependencies to run this framework.
- Hello : Is a command only for local environment (that can be deleted) only for demo purposes.
- Example : Is a command only for local environment (that can be deleted) only for demo purposes.
- Addresses : Is a command only for local environment (that can be deleted) only for demo purposes.
Run Commands
To run Commands use micra
PHP executable.
./micra [command-name]
If you need help:
./micra -h
If you need Command help:
./micra [command-name] -h
Models
Manages the data, logic and rules of the application.
You can add as many Models as you want in a cleaning way (/app/Models
).
After add your Models, you use it for, for example, in a Controller.
NOTE: To have helpers you must extend the Model with ModelAbstract located in \App\Kernel\Abstracts
.
use App\Kernel\Abstracts\ModelAbstract; use PDO; class AddressesModel extends ModelAbstract { /** * Get Last Addresses with Pdo * * @param int $limit * @return array */ public function getLastWithPdo(int $limit = 25): array { /** @var $db PDO */ $db = $this->getDb()->pdo; $sql = 'SELECT `address`.`address_id`,`address`.`address`,`address`.`address2`,`address`.`district`,`city`.`city`,`address`.`postal_code`,`address`.`phone` FROM `address` '; $sql .= 'LEFT JOIN `city` ON `address`.`city_id` = `city`.`city_id` '; $sql .= 'ORDER BY `address_id` DESC LIMIT 10'; return $db->query($sql)->fetchAll(PDO::FETCH_ASSOC); }
Models Helpers
getApp()
- Returns App objectgetContainer(string $name)
- Returns the App ContainergetConfigs(string $name)
- Returns App ConfigsgetService(string $service)
- Returns Service Provider from container by namegetDb()
- Returns Database object
Services Providers
Define bindings and inject dependencies.
You can add as many Services Providers as you want in a cleaning way (/app/Services
).
After add your Services Provider, you can enable or disable it in configs/services.php
configuration file.
NOTE: Service Providers must respect the ServiceProviderInterface located in \App\Kernel\Interfaces
.
use App\Kernel\Interfaces\ServiceProviderInterface; use Pimple\Container; class ExampleServiceProvider implements ServiceProviderInterface { /** * Service register name */ public function name(): string { return 'example'; } /** * Register new service on dependency container * * @param Container $container * @return mixed */ public function register(Container $container) { return function (Container $c) { unset($c); return new Example(); }; } }
Enable it in configs/services.php
:
use App\Services\Example\ExampleServiceProvider; return [ 'example' => ExampleServiceProvider::class, ];
Handlers
Handles specified behaviors of the application.
You can override the following Handlers in a cleaning way (/app/Handlers
):
- ErrorHandler (default located in
/app/Handlers/ErrorHandler
) - ShutdownHandler (default located in
/app/Handlers/ShutdownHandler
)
After add your Handler, you can enable or disable it in configs/app.php
configuration file.
use App\Handlers\ErrorHandler; use App\Handlers\ShutdownHandler; return [ // Handlers // 'errorHandler' => ErrorHandler::class, 'shutdownHandler' => ShutdownHandler::class,
Database Support
Medoo is implemented out of box as a Service Provider. The use is optional and is not enabled by default.
To enable database support with Medoo you need to add this library/vendor with Composer:
composer require catfan/medoo
Once installed you need to enable the Service Provider in configs/services.php
:
use App\Services\Database\DatabaseServiceProvider; return [ 'database' => DatabaseServiceProvider::class, ];
Now you are ready to use it...
If you need more details, documentation, api reference, please visit Medoo webpage: https://medoo.in/
NOTES:
- Don't forget to load PDO extensions for your database. For example, if you need MySQL, you need to install
pdo_mysql
PHP extensions. - You can use another library as a Service Provider (Native drivers for MySQLi, PostgreSQL, MongoDB, Redis, ...).
Exceptions
You have some Exceptions out the box, located in \App\Kernel\Exceptions
, than you can use it:
CommandException - For Commands Exceptions
ConfigsException - For Configurations Exceptions
ModelException - For Models Exceptions
ServiceException - For Service Providers Exceptions
Logging
Logging is always enabled and you can see all the output in /storage/logs/app-[date].log
.
NOTE: Logs will with more than 7 days will be deleted automatically by the Logger.
Benchmarks
Some numbers for Hello Command...
Machine:
Intel® Core™ i5-8400 CPU @ 2.80GHz × 6
16Gb RAM
SSD
Versions:
Ubuntu 20.04 LTS
Docker v19.03.8
PHP v7.4.3
PHP v7.2.24
Zend OPcache enabled