Download the PHP package not-empty/ala-microframework-php without Composer

Lumen ALA

API Rest based in lumen using query builder that auto generate base code for simple crud (with automatic generated 100% unit and feature tests).

Release 7.0.0 Requires PHP 8.3

Release 6.0.0 Requires PHP 8.2

Release 5.0.0 Requires PHP 8.1

Release 4.0.0 Requires PHP 7.4

Release 3.0.0 Requires PHP 7.3

Release 2.0.0 Requires PHP 7.2

Release 1.0.0 Requires PHP 7.1

Installation

composer create-project and enter in the created folder (you can fork or clone the repository if you want to)

(optional) Stop all other containers to avoid conflict.

Start project with Docker using compose tool.

Access the container

Run Composer to install all dependencies.

Ensure the composer install create the cache folders and give then permissions in ./storage, if don't you'll have to create and give permitions yourself:

To check the build for this project look at ./ops/docker/dev folder.

Copy and modify the .env file

Include values for APP_KEY and JWT_APP_SECRET, we strongly recommend a 26 to 32 length random string (can be a ulid)

You can use /health/key uri to generate this keys.

Now you can access the health-check http://localhost:8101 and get a json response like this:

Creating your automatic crud domain

For create your brand new domain with a complete crud use the command:

This command will create a folder in app/Domains, new files in routes, database/migrations and database/seeds folder with all base code including all the units and feature tests.

If your domain name has 2 words use underline (_) to separate.

Configuring your new Domain

• Configure your migration file in database/migrations with all your fields and indexes
• Open your domain and configure your fields and the order in app/Domains/{your_domain}/Http/Parameters
• Your validator rules can be configured in app/Domains/{your_domain}/Http/Validators
• You can modify or add more business rule in app/Domains/{your_domain}/Businesses
• Or your routes in bootstrap/{your_domain}_routes folder

Running your Migration

• Once you have configured your migration file in database/migrations;
• Run the migration

Requests samples

Within the /ops/requests folder, you'll discover a collection of sample requests showcasing.

Requests have been meticulously documented in three different formats for your convenience:

1. Postman Collections

Files: postman_collection.json and postman_environments.json

Tool: Postman

These collections provide a comprehensive overview of the available API requests. Import them into Postman to explore and execute requests seamlessly.

2. Visual Studio Code (VSCode) REST Client Extension:

File: requests.http

Extension: REST Client

With the extension installed in VSCode open the requests.http file. This extension allows you to send HTTP requests directly from your code editor, making it easy to interact with the API.

3. CURL Commands:

File: requests.curl

For those who prefer the command line, CURL commands are provided in the requests.curl file. Execute these commands in your terminal to interact with the API using the widely-used CURL tool.

Choose the documentation format that aligns with your preferred workflow and start seamlessly interacting with the API.

Ulid

For primary key value, this project using Ulid value, but you can pass other pattern in insert route if you prefer.

JWT

In auth route this projet use JWT lib. This token will be generate if your secret, token and context is correct. This configuration is the token.php file in app/config/ folder.

We strongly advise you to change these values, they can be either random strings, ulids or any string that you like.

We use to generate then by encrypting an ulid v4 with SHA512/256.

We recommend creating diferents tokens from diferents sources.

Request Service

To make request between two or more services, this project use Request Service lib.

Response

The pattern used to return all request is json and the layout is configure in your Response lib.

Custom Validators

I you want to implement custom validators you can use the regex function and add you regex to the patterns file /app/Constants/PatternsConstants.php and then just use anywhere but dont forget to declare the class for use:

Filters

Follow this steps to configure a new field to accepted a filter in list route

• In your domain validators list file app/Domains/{your_domain}/Http/Validators/{your_domain}ListValidator you can change or add more filters options.

For example, to add a filter to age field just include a new entry like that

After that, you need to configure your filters in app/Domains/{your_domain}/Filters.

you can user various patterns like FILTER_EQUAL, FILTER_NOT_EQUAL, etc.

Check all types look at FiltersTypesConstants class in app/Constants.

After that you can send this param in url query, for example:

/{your_domain}/list?filter_name=lik,vitor OR /{your_domain}/list?filter_name=eql,vitor.

Recomendations

Use this project with MySql with no relationship keys and NOT use JOIN.

Production

Don't forget to change APP_ENV to production value. This enable the op_cache PHP extension, so dont use in development environment.

The production docker is located in ops/docker/prod and you can change the Nginx config or PHP all the way you want.

Development

Want to contribute? Great!

Make a change and be careful with your updates! Any new code will only be accepted with all validations.

To ensure that the entire project is fine:

First install the dependences (with development ones)

Second run all validations

You can run all validations plus test coverage metrics

Code Quality

We create this project under stricts good pratices rules. Bellow you can see some composer commands to validate the framework code and your code as well.

We recommend you aways run the composer checkallcover command to validate all your code, tests and coverage.

lint - check for sintax errors on PHP (PHP Lint)

cs - check for smells in general (Code Snifer)

mess - check for smells in a more deep way (Mess Detector)

test - run all tests (Unit and Feature)

test-cover - run all tests with code coverage (Unit and Feature)

test-unit - run all unit tests

test-unit-cover - run all unit tests with code coverage

test-feat - run all feature tests

test-feat-cover - run all feature tests with code coverage

ccu - check unit coverage level (100% is required)

ccf - check feature coverage level (100% is required)

check - execute lint, cs, mess and unit tests

checkcover - execute lint, cs, mess and unit tests with coverage

checkall - execute lint, cs, mess, unit and feature tests

checkall - execute lint, cs, mess, unit and feature tests with coverage

Sonarqube

This project is also validated with Sonarqube, has a sonar-project.properties file to support sonarqube execution.

To do that, edit the sonar-project.properties with your sonar url (maybe something like http://192.168.0.2:9900 if you running sonar in your machine), and then execute sonar scan.

Automatic Validation Before Commit

If you want to force the checkallcover in your project before commit, you can just copy the file ops/contrib/pre-commit to your .git/hook. Be aware your development environment will need to have PHP with xdebug installed in order to commit.

Random Seed Data

You can create an automatic seeder to generate data using you add endpoint to tests purposes (or any other purpose you like).

To do that you must create a random seeder with the command:

It will create a file inside app/Seeds/ with your domain name with all possibilities.

You may change to fullfill your needs (and your domain validations)

Now you may configure on .env the SEED_URLand SEED_PORT environments. (if you want to run inside docker don't change at all).

And run your seed with the domain name and the amount to records to generate.

Then use the list endpoint, or make a select in database to see the results.

Not Empty Foundation - Free codes, full minds