rougin/weasley

Generators and helpers for the Slytherin framework.

Weasley

![Software License][ico-license] ![Coverage Status][ico-coverage] , _(*1)

Weasley is a PHP package that provides generators, helpers, and utility classes for the Slytherin. Its goal is to improve the overall productivity when writing web applications based on Slytherin by reducing in writing code related to CRUD operations., _(*2)

Installation

Install the Weasley package via Composer:, _(*3)

``` bash $ composer require rougin/weasley, <sub>(*4)</sub>

Once installed, kindly see the following features below provided by `Weasley`:

## Code generators

`Weasley` provides commands that generates code based on the specified type (e.g., `Check`, `Route`, etc.). These commands allow `Slytherin` to be a rapid prototyping tool in creating web-based applications.

To access the list of available commands, kindly run its namesake command from the terminal:

``` bash
$ vendor/bin/weasley

make:check

Creates a new check (validation) class based on Valitron., <sub>(*5)</sub>

make:handler

Creates a new HTTP Middleware class., <sub>(*6)</sub>

make:package

Creates a new Slytherin Integration class., <sub>(*7)</sub>

make:route

Creates a new HTTP route class., <sub>(*8)</sub>

HTTP routes

In creating web applications, Weasley also provides PHP classes to create HTTP routes based on the RESTful style., <sub>(*9)</sub>

[!NOTE] In other PHP frameworks, this is also known as Controllers., <sub>(*10)</sub>

HttpRoute

A simple HTTP route class for RESTful APIs., <sub>(*11)</sub>

JsonRoute

Similar with HttpRoute but the response will be returned in JSON format., <sub>(*12)</sub>

Third-party packages

To conform with the usage of IntegrationInterface from Slytherin, Weasley also provides the following third-party integrations with other PHP packages:, <sub>(*13)</sub>

Laravel\Eloquent

This package enables the usage of Eloquent to Slytherin which is an Object-relational mapper (ORM) from Laravel. To use this package, kindly install its required package first in Composer:, <sub>(*14)</sub>

``` bash $ composer require illuminate/database, <sub>(*15)</sub>

### `Laravel\Blade`

`Laravel\Blade` allows `Slytherin` to use [Blade](https://laravel.com/docs/blade) from `Laravel` for creating PHP templates using the `Blade` templating engine. Use the command below to install the specified package from `Composer`:

``` bash
$ composer require illuminate/view

Laravel\Paginate

This is a simple third-party package that allows Eloquent to generate pagination links based on its models. Kindly use the command below to install this third-party package:, <sub>(*16)</sub>

``` bash $ composer require illuminate/paginate, <sub>(*17)</sub>

### `Session`

`Weasley` also provides a simple implementation of the [SessionHandlerInterface](https://secure.php.net/manual/en/class.sessionhandlerinterface.php).

## HTTP handlers

`Weasley` has the following HTTP middlewares (HTTP handlers in this case) to improve the handling of HTTP requests and its respective responses:

### `AllowCrossOrigin`

Adds additional headers for [Cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) (CORS).

### `EmptyStringToNull`

Converts the empty strings from request as `null`.

### `JsonContentType`

Changes content response to `application/json`.

### `MutateRequest`

A middleware that can be extended to mutate/transform values from the request.

### `SpoofHttpMethod`

Replaces the HTTP verb  from `_method` value.

### `TrimStringValue`

Trims the strings from an incoming request.

## Mutators

Provided by `Weasley`, mutators are classes that mutates (transforms) to a specified result (e.g., [PSR-07](https://www.php-fig.org/psr/psr-7/) responses, API data, etc.):

### `JsonMutator`

Mutates a `PSR-07` response in JSON format.

### `RestMutator`

Mutates a response created from the `Laravel/Paginate` package based on [Paypal's API Style Guide](https://web.archive.org/web/20220114091735/https://github.com/paypal/api-standards/blob/master/api-style-guide.md).

## Validation

`Weasley` also provides a simple validation class on top of [Valitron](https://github.com/vlucas/valitron) using the `Check` class:

``` php
use Rougin\Weasley\Check;

class UserCheck extends Check
{
    protected $labels =
    [
        'name' => 'Name',
        'email' => 'Email',
        'age' => 'Age',
    ];

    protected $rules =
    [
        'name' => 'required',
        'setting' => 'required|email',
        'type' => 'required|numeric',
    ];
}

Once created, the data can be submitted to the said class for validation:, <sub>(*18)</sub>

``` php $check = new UserCheck;, <sub>(*19)</sub>

$data = /* e.g., data from request */;, <sub>(*20)</sub>

if ($check->valid($data)) { // $data passed from validation } else { // Get the available errors --- $errors = $check->errors(); // ----------------------------, <sub>(*21)</sub>

// Or get the first error only --- echo $check->firstError(); // ------------------------------- }, <sub>(*22)</sub>

## Testing

If there is a need to check the source code of `Weasley` for development purposes (e.g., creating fixes, new features, etc.), kindly clone this repository first to a local machine:

``` bash
$ git clone https://github.com/rougin/weasley.git "Sample"

After cloning, use Composer to install its required packages:, <sub>(*23)</sub>

``` bash $ cd Sample $ composer update, <sub>(*24)</sub>

> [!NOTE]
> Please see also the [build.yml](https://github.com/rougin/weasley/blob/master/.github/workflows/build.yml) of `Weasley` to check any packages that needs to be installed based on the PHP version.

Once the required packages were installed, kindly check the following below on how to maintain the code quality and styling guide when interacting the source code of `Weasley`:

### Unit tests

`Weasley` also contains unit tests that were written in [PHPUnit](https://phpunit.de/index.html):

``` bash
$ composer test

When creating fixes or implementing new features, it is recommended to run the above command to always check if the updated code introduces errors during development., <sub>(*25)</sub>

Code quality

To retain the code quality of Weasley, a static code analysis code tool named PHPStan is being used during development. To start, kindly install the specified package in the global environment of Composer:, <sub>(*26)</sub>

``` bash $ composer global require phpstan/phpstan --dev, <sub>(*27)</sub>

Once installed, `PHPStan` can now be run using its namesake command:

``` bash
$ cd Sample
$ phpstan

[!NOTE] When running phpstan, it will use the phpstan.neon file which is already provided by Weasley., <sub>(*28)</sub>

Coding style

Aside from code quality, Weasley also uses a tool named PHP Coding Standards Fixer for maintaining an opinionated style guide. To use this tooling, it needs also to be installed in the Composer's global environment first:, <sub>(*29)</sub>

``` bash $ composer global require friendsofphp/php-cs-fixer --dev, <sub>(*30)</sub>

After its installation, kindly use the `php-cs-fixer` command in the same `Weasley` directory:

``` bash
$ cd Sample
$ php-cs-fixer fix --config=phpstyle.php

The phpstyle.php file provided by Weasley currently follows the PSR-12 standard as its baseline for the coding style and uses Allman as its indentation style., <sub>(*31)</sub>

[!NOTE] Installing both PHPStan and PHP Coding Standards Fixer requires a minimum version of PHP at least 7.4., <sub>(*32)</sub>

Changelog

Please see CHANGELOG for more information what has changed recently., <sub>(*33)</sub>

License

The MIT License (MIT). Please see LICENSE for more information., <sub>(*34)</sub>