Download the PHP package moorexa/fatapi without Composer

FATAPI

A Powerful REST API Framework for small and large projects.

Crafted for PHP developers. It's great for personal, enterprise, and commercial backend applications.

Why FatApi

Building backend applications for years led us to this one stop solution. Over the years we've built REST API's with the following request methods GET, POST, DELETE, PUT and we've also had to worry about;

1. Versioning
2. Building light then scalling to micro services
3. Managing multiple endpoints that are procedural
4. Creating standards for our requests and responses even when contracting some part of our backend application to remote developers
5. Generating documentation for every services without writing one line of code.
6. Getting extra stuffs done like obtaining packages for authentication, middlewares, live documentation, plugins and much more from a marketplace so we don't have to reinvent the wheel.

Yeah, creating this takes so much time, and many startups, developer, or software agency would worry less if they had a foundational system like this that allows:

1. Connectivity to external services
2. Creating small programs that can be decoupled into micro services when the business scales
3. Building strict entities that are consitent across versions
4. Generating responses that follow standards, easy to comprehend and consistent with formats
5. Clean URL that explains what it does, allowing developers to obtain documentation with an additional request header x-meta-doc
6. Reduced cost in managing multiple endpoints and do more without having to add request ID's to your endpoints, keeping it neat and enjoyable.
7. Adopting new request standards that takes out DELETE and PUT request methods but, out of the box lets you can do lot more with only GET and POST request methods which has made FATAPI so unqiue and easy to work with.
8. Also allow you use all request methods for external services. Yeah, FATAPI also serves as a gateway, connecting you to other services you may have on multiple servers, and allow you version them with no sweat.
9. Getting up to speed by obtaining services, middlewares, plugins, documentation templates and much more from the FatApi Marketplace.

The list can go on and on. This is a low code movement and we what to help you increase productivity by getting your backend rolled out in no time, properly documented and enjoyable.

Architectural Style or Pattern

1. Event-Bus pattern
2. Micro-Services
3. Monolithic or Peer pattern

Requirements

1. PHP 7 and above
2. Knowledgeable in PHP and OOP
3. Added knowledge of Moorexa ORM is a plus but not neccessary, everything is auto generated for you.

Installation

It's way easy!!! Ensure that you have composer installed and run the create-project command below

The command above will create a “project-name” folder.

If you omit the “project-name” argument, the command will create an fatapi folder, which can be renamed as appropriate.

Running this command will install all you need, including local composer and all the required dependencies.

Getting Started

First, we must authorize every requests. And to do that, we just need to generate a token from the command line using

Where {unqiue name} can be the name of your project or something unique to you. Next, we update the MustBeAuthorized middleware located in src/Middlewares/. You can also check out the FatApi marketplace for authorization middlewares that allow you do much more like rate limter, timeout etc.

By default, we've added MustBeAuthorized middleware so you can still get stuffs done without needing to go premium at this point.

After generating this token, you should get a token size of 40, copy it and update the MustBeAuthorized middleware as seen below.

The token should be your newly generated token. Next, you can now share this token to be added to the authorization header for every incoming request as seen below.

Find help for a request method

Avaliable CLI Commands

Here are commands that can help you speed up development.

How to create a new service

Services are like resources that contains one or more routes. They are packed with providers, models and some helpful classes and methods for building a functional and scalable systems. Here we demostrate how to use the command line to generate one.

where {service} can be a string without special characters execpt (_) and (-) eg. service-name, myservice, user, account, etc.

By default, if you don't include a version to the command, it generates that service with the default version v1. But just incase you want a new version, just specify it as seen below

After creating a service called User for example on version v1 you should see the following files and folders

Folder and file breakdown

How to create a new route

Creating a route requires that you must have already generated a service and that the route does not exists for that service. A route would be a trigger to complete a transaction and they typically would take the request data sent, provide some inner workings that makes meaning to the data, and then send a response back through json or xml. Every service must have at least one or more route to be successful and below we would show you a basic command to generate one;

Where {option} can either be (post or get). So why {option}? They help be direct to where you what that route to be added. Remember we have two main request files called PostUser.php and GetUser.php using a User service as an example.

Where {service} is a valid service name that exists in your src/Resource/{version} folder.

Where {route} is a valid method that does not exists in the method eg. submit-profile, etc.

Create a route with a version number

You simply need to add a version number after the route name as seen below;

Where {version} can be v1, v2, etc.

Create a route without an option

You can also benefit from some naming standard we've designed so that you stay consistent with your route names. This implies that you no longer need to add -post or -get when creating a route. The table below shows just how, and we would demostrate with a service called User;

How to make a simple POST request

To demostrate this, we would be using nodejs and the axios library. Take note of /api, that's our single point of entry.

To obtain more information of what's required to send a request to the server, make this simple request to obtain help.

or just sent a POST request to that url to learn more.

How to make a simple GET request

To demostrate this, we would be using nodejs and the axios library. Take note of /api, that's our single point of entry.

To obtain more information of what's required to send a request to the server, make this simple request to obtain help.

or just sent a GET request from your browser to that url to learn more.

Resource configuration style

Here you can instead generate a config.json file and transfer request to an external service using a general style or separate channel with different request method.

Here is a general request style that takes all the request and just push to one endpoint.

General request style 1

Here is a breakdown of what's happening

Make GET or POST request using Socket.io

At any point in time you desire to utilize socket programming to facilitate communication instead of HTTP requests, we just might have a simple solution for you. Before you continue, ensure that you have

installed or just run

from your cmd or terminal to install all dependencies for socket.io.

Next, we start our socket server by running the following command

This would start workerman socket server with the address ws://0.0.0.0:8082. And you can change this default settings here framework/src/environment.yaml

Sending a socket.io request with Javascript

To do this, you must have obtained socket.io cdn or installed socket.io client. Here, we would demostrate a complete proceedure to get you up to speed.

Sending a socket.io request with PHP

To do this, you don't need to install any dependency. Here, we would demostrate a complete proceedure to get you up to speed.

At the moment, it makes sense to use the PHP implementation if you don't need to wait and listen for a response as demostrated for javascript. It comes handy when you need to send data to other services within the program.

Here is a complete breakdown on the sample data sent to meta.api

How to use a model in a service

Lets assume that you have created a service and a model. Your model should be avaliable to use from a namespace.

For this example, we would assume a test model in src/Resources/Student/v1/Model/. See a summary of what it should look like;

Now for every request that's sent to a service, there exists a Request and Response class parameters. And this Request class holds the request data that has been validated and verified along side a method called useModel() that takes a model class name as a string and loads all the request data into that class for database operations. To demostrate this, we would assume a POST request to the Student service to the default Init method.

Getting a request ID

You have passed an ID to your request parameter or used the x-meta-id method to send an ID with your request? See how to get it below from a service method.

How to connect your model to a database

First you need to have created a model file, next we create a new connection with the command below

Where sessionConnection can be any valid function name.

This would create a new method sessionConnection() in Engine\DBMS class located in src/Engine/DBMS.php.

The content of this method should look like this:

Next, you set the value of $connectionName to match a connection key created in Moorexa src/database/database.php file. An example of this could be the default 'new-db' connection key. So now, your connection method should look like this

If connectionName is left empty, Moorexa would try to use the default connection settings in src/database/database.php. Which means that you have to set a value for development or live. See example below

Perharps you might like to add another connection setting so you make do of multiple connection settings, use the command below

Where connectionName is something you would like to identify that connection with.

Next you open your model file and set the value of $DBMSConnection to the new method sessionConnection or your unquieMethodName created in Engine\DBMS class located in src/Engine/DBMS.php. See example below;

Now, your model is connected to a database using that connection method which typically fulfils every query through a connection key found in src/database/database.php.

How to apply a middleware to a resource

Middleware provides services to your resources beyond those available from the core system. It can be described as "service glue". Creating one is simple and can be done with the following command below, where MIDDLEWARE_NAME is something unquiue to you.

Lets assume that we have called our middleware MustBeAuthorized, now we can apply it to a resource service class or method. To do this, open src/Resources/middleware.json. To demostrate this, we would apply this for every post requests particular to a service called Student, We can even go further by adding more to the array or be direct to a specific class method Profile.

How to apply a middleware to a method directly

Middlewares can now be added to your methods directly as part of the doc comment. We would demostrate with our assumed middleware MustBeAuthorized which can be found in src/Middlewares/.

Take note of the tag @middleware! Now, every request into that route must pass that middleware before dealing with the request body. You can have more than one middleware as seen below

How to filter every input from a request

You just need to add an entry to the src/Resources/input.json file and then the system ensures that what is presented to you has been checked and passed. Else, it stops processing the request and asks the developer for the correct/required data. Now, lets take an example to demostrate, we call this service student with a method called login. This request method will be POST and would trigger the class file PostStudent in the Student resource folder. Now, to lock on this request for the required data we just add this to our src/Resources/input.json file

If this is successful, it makes the data (username and password) avaliable to you via the Engine\Request class. And to demostrate see

Now using a model as showned in this documentation would pre-fill this request data to your model or you customize your model like this also;

How to switch versions

You can do this from the src/Resources/versioning.json file for different request methods. Lets paint a scenario, You've built your services and now you want your consumers to use a new version without having to update your frontend? This is possible for not just a service but for a specific method also. How do we do this? see example below

ExampleService is just a placeholder and can be your service name eg (student, user, account, etc.). To update the default version of a service method, just add a dot(.) followed by the service method. See example below;

Default Query Filter for Get Requests

A great API is not complete without search and filters, this we know and here we've built more than one option to manage what to recieve without writing additional code. Here are some of the GET queries you can add to your URL.

1. ?sort=asc or desc
2. ?column=* or name,age etc
3. ?limit=0,4 or more
4. ?sortby=column|asc or desc
5. ?rowid={0-9 or string}
6. ?search=column|data

Model Special methods

Sending Transactional and Business Emails

Out of the box, you can now send emails using the symfony/mailer package. We've extended this library to simplify it use cases starting from configuration down to sending mails with attachments and more. For more information on this package please visit [https://symfony.com/doc/current/mailer.html]

Having that out of the way, let's begin with the configuration. Open the file src/Messaging/Emails/config.php to make your configuration.

Our default handler for the SymfonyMailer package is Messaging\Emails\Handlers\SymfonyMailer::class and you can change it if you feel like.

Next, creating dynamic methods and linking them to a template file

You've got it already, from the src/Messaging/Emails/email-list.json file you can just add dynamic methods that would represent one or more template files. See an example below;

The template "welcome" represents a template file that must have been created in src/Messaging/Emails/Templates/Business/ directory as welcome.html and may contain one or more placeholders to mask actual data. You can also see the category. So far we have two categories and i'll take you where their template files lives;

You are free to create more categories with additional methods that points to where a template can be fetched when called by the category name in src/Messaging/Emails/EmailTemplate.php.

"entities" tells what to expect from the developer. These fields can contain default data as seen below:

The rest is self explanatory. Now, we can send a mail to any email address from anywhere in our application. See example below

Sending Background Emails

Out of the box you can use the rabbitmq server and client for this. Moorexa already made this easy. Just ensure that you have your rabbitmq-server running and then you can run the following command on your cli to start the client listener;

Now you can now send background processes like emails, image processing and more. See Doc guide: https://rabbitmq.com/documentation.html for rabbitmq-server

Sending Email Alerts

We've created a class called Messaging\EmailAlerts::class that houses all alerts to your server once a transaction is completed. A transaction can either be;

1. New customer order
2. New sign up
3. Failed purchase etc.

These alerts can be added in the Messaging\EmailAlerts class in src/Messaging/EmailAlerts.php and called from that namespace when the need arises. See an example below

Remember, all alerts must have a template file saved in src/Messaging/Emails/Templates/Business/ for business and src/Messaging/Emails/Templates/Transactional for transactional mails like "login, confirm password" etc.

There you go, have fun building great stuffs with it.