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
  • Development Only
• Configurations
  • Dot Notation
• Commands
  • Helpers
  • Inbuilt
• Run Commands
• Models
  • Models Helpers
• 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 instance
• container(string $name) - Returns Container registered data
• configs(string $variable, string $default) - Returns Configuration data
• base_path(string $path) - Returns base path location
• app_path(string $path) - Returns app path location
• configs_path(string $path) - Returns configs path location
• storage_path(string $path) - Returns storage path location

Global Helpers for Development Only

• dump($var1, $var2, ...) - Dump vars
• dd($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 object
• getContainer(string $name) - Returns the App Container
• getConfigs(string $name) - Returns App Configs
• getService(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 object
• getContainer(string $name) - Returns the App Container
• getConfigs(string $name) - Returns App Configs
• getService(string $service) - Returns Service Provider from container by name
• getDb() - 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

Enjoy the simplicity :oP