php-utils
PHP Utilities for Laravel/Lumen
Installation
cd /path/to/your/project
composer require logcomex/php-utils
Utilities Packages
- Contracts
- Exceptions
- Functionalities
- Handlers
- Helpers
- Loggers
- Logs
- Middlewares
- Providers
- Singletons
Contracts
Have all the contracts (interfaces) used by the php-utils classes and other that you can use in your project.
Exceptions
Have all the exceptions used by the php-utils classes. And others that you can use in your project to segregate your errors types .
ApiException
You can use for all exceptions in 400 range http code
ApiException(string $token,
string $message,
int $httpCode = Response::HTTP_BAD_REQUEST,
Exception $previous = null)
| Visibility | Function | Return Type |
|---|---|---|
| public | getHttpCode | int |
| public | getToken | string |
| public | __toString | string |
| public | toArray | array |
| public | toJson | string |
BadImplementationException
This exception means that a situation has been overlooked or incorrectly done by the developer.
BadImplementationException(string $token,
string $message,
int $httpCode = Response::HTTP_INTERNAL_SERVER_ERROR,
Exception $previous = null)
| Visibility | Function | Return Type |
|---|---|---|
| public | getHttpCode | int |
| public | getToken | string |
| public | __toString | string |
| public | toArray | array |
| public | toJson | string |
SecurityException
This exception serves to point out some security problem in your application.
SecurityException(string $token,
string $message,
int $httpCode = Response::HTTP_FORBIDDEN,
Exception $previous = null)
| Visibility | Function | Return Type |
|---|---|---|
| public | getHttpCode | int |
| public | getToken | string |
| public | __toString | string |
| public | toArray | array |
| public | toJson | string |
UnavailableServiceException
This exception serves to point out that your or other application is unavailable.
UnavailableServiceException(string $token,
string $message,
int $httpCode = Response::HTTP_FORBIDDEN,
Exception $previous = null)
| Visibility | Function | Return Type |
|---|---|---|
| public | getHttpCode | int |
| public | getToken | string |
| public | getService | string |
| public | __toString | string |
| public | toArray | array |
| public | toJson | string |
Functionalities
They're a pack of traits that can be useful in your code
PropertiesExporterFunctionality
You can use this functionality to export an array with you class properties
public static function properties(): array
PropertiesAttacherFunctionality
You can use this functionality to attach in your class properties the values passed in the parameter.
Note: To uses this functionality, you need use the PropertiesExporterFunctionality in the class.
public function attachValues(array $values): void
| Exception | Reason |
|---|---|
| BadImplementationException | When you don't use PropertiesExporterFunctionality |
ValuesExporterToArrayFunctionality
You can use this functionality to easily get all the properties of class in an array.
Note: To uses this functionality, you need to do two things:
- The class must implement Illuminate\Contracts\Support\Arrayable.
- The class must use PropertiesExporterFunctionality.
public function toArray()
| Exception | Reason |
|---|---|
| BadImplementationException | When yout don't implement the the Arrayable contract |
| BadImplementationException | When you don't use PropertiesExporterFunctionality |
ValuesExporterToJsonFunctionality
You can use this functionality to easily get all the properties of class in a Json.
Note: To uses this functionality, you need to do two things:
- The class must implement Illuminate\Contracts\Support\Jsonable.
- The class must use PropertiesExporterFunctionality.
public function toJson()
| Exception | Reason |
|---|---|
| BadImplementationException | When yout don't implement the the Jsonable contract |
| BadImplementationException | When you don't use PropertiesExporterFunctionality |
Helpers
They're a pack of Helpers classes and traits.
EnumHelper
It's a trait that provide some utilities to your Enumerators classes.
| Visibility | Function | Return Type | Purpose |
|---|---|---|---|
| public | all | array | Get all the constants of your Enumerator |
use Logcomex\PhpUtils\Helpers\EnumHelper;
class ProductEnum
{
user EnumHelper;
public const EXAMPLE = 'example';
public const EXAMPLE2 = 'example2';
}
$allProducts = ProductEnum::all();
Loggers
The idea of this package is provide all the Loggers classes.
LogcomexLogger
Using this class you can easily provide a log template, that is very important to integrate with Datadog.
// bootstrap/app.php
$app->register(Logcomex\PhpUtils\Providers\LogcomexLoggerProvider::class);
$app->withFacades(true, [
Logcomex\PhpUtils\Facades\Logger::class => 'Logger',
]);
Logger::info('TOKEN-001', ['reason' => 'test',]);
Middlewares
They're a pack of Middleware classes.
AuthenticateMiddleware
It is a class that provides authentication verification. You'll need a AuthProvider configured in your application to use this Middleware.
// bootstrap/app.php
$app->register(Your\Provider\AuthServiceProvider::class);
// Using in global mode
$app->middleware([
Logcomex\PhpUtils\Middlewares\AuthenticateMiddleware::class,
]);
// Or, by specific route
$app->routeMiddleware([
'auth' => Logcomex\PhpUtils\Middlewares\AuthenticateMiddleware::class,
]);
RequestLogMiddleware
It is a class that provides a log for each request in your api. You can choose what you gonna print in the log, such as: request-header, request-server, request-payload, response-header, response-content, response-time, and trace-id.
The .env configuration:
| Env Variable | Type | Description |
|---|---|---|
| REQUEST_LOGGER_ENABLE_REQUEST_HEADER | boolean | Print in the log, the request header information |
| REQUEST_LOGGER_ENABLE_REQUEST_SERVER | boolean | Print in the log, the request server information |
| REQUEST_LOGGER_ENABLE_REQUEST_PAYLOAD | boolean | Print in the log, the request payload information |
| REQUEST_LOGGER_ENABLE_RESPONSE_HEADER | boolean | Print in the log, the response header information |
| REQUEST_LOGGER_ENABLE_RESPONSE_CONTENT | boolean | Print in the log, the response content information |
| REQUEST_LOGGER_ENABLE_RESPONSE_TIME | boolean | Print in the log, the response execution time information |
| REQUEST_LOGGER_ALLOWED_DATA_REQUEST_SERVER | string | If has data in this variable, the middleware gonna print just the infos requested in this setting |
// config/requestLog.php
return [
'enable-request-header' => env('REQUEST_LOGGER_ENABLE_REQUEST_HEADER', true),
'enable-request-server' => env('REQUEST_LOGGER_ENABLE_REQUEST_SERVER', true),
'enable-request-payload' => env('REQUEST_LOGGER_ENABLE_REQUEST_PAYLOAD', true),
'enable-response-header' => env('REQUEST_LOGGER_ENABLE_RESPONSE_HEADER', true),
'enable-response-content' => env('REQUEST_LOGGER_ENABLE_RESPONSE_CONTENT', true),
'enable-response-time' => env('REQUEST_LOGGER_ENABLE_RESPONSE_TIME', true),
'allowed-data-request-server' => explode(';', env('REQUEST_LOGGER_ALLOWED_DATA_REQUEST_SERVER', '')),
];
// bootstrap/app.php
$app->configure('requestLog');
// Using in global mode
$app->middleware([
Logcomex\PhpUtils\Middlewares\TracerMiddleware::class, // If you gonna use tracer, it must be above the requestlog
Logcomex\PhpUtils\Middlewares\RequestLogMiddleware::class, // And after trace, you need the request log
]);
ResponseTimeLogMiddleware
It is a class that registers the response time of each request in your api. You can choose what request will be measured through calling the middleware by route.
First of all, you have to define the framework start time globally before requiring anything in your bootstrap:
// bootstrap/app.php
if (!defined('GLOBAL_FRAMEWORK_START')) {
define('GLOBAL_FRAMEWORK_START', microtime(true));
}
Configuration:
Your app config has to contain the key 'api-name', which will be used by this middleware for identifying what API the response time belongs to.
// bootstrap/app.php
$app->configure('app');
Usage:
It is IMPORTANT that you call this middleware as the first one, so the response time calc can be the most accurate as possible.
// Using in global mode
$app->middleware([
Logcomex\PhpUtils\Middlewares\ResponseTimeLogMiddleware::class,
]);
// Using in specific routes
$app->routeMiddleware([
'response-time-log' => Logcomex\PhpUtils\Middlewares\ResponseTimeLogMiddleware::class,
]);
Route::group(
[
'prefix' => 'example',
'middleware' => ['response-time-log'],
],
function () {
Route::get('responseTimeLog', 'ExampleClassName@exampleMethodName');
});
TracerMiddleware
It is a class that provides tracer functionality for your api. So your log can use this value and the HttpHelper. You must create a tracer config file in config folder. We recommend uses this middleware as global, and the first one in middlewares chain.
// config/tracer.php
return [
'headersToPropagate' => explode(';', env('TRACER_HEADERS_TO_PROPAGATE')),
];
// bootstrap/app.php
$app->configure('tracer');
// Using in global mode
$app->middleware([
Logcomex\PhpUtils\Middlewares\TracerMiddleware::class,
// the other middlewares
]);
// Or, by specific route
$app->routeMiddleware([
'tracer' => Logcomex\PhpUtils\Middlewares\TracerMiddleware::class,
]);
AccreditedApiKeysMiddleware
It is a class that provides a first level of security for your api. The best analogy is that middleware is your "API guest list".
You need to register a configuration file called accreditedApiKeys, with all the api-keys that can request your api.
Therefore, if the request does not contain the x-infra-key header or a allowed value, the API denies the request with the security exception.
It is recommended to use as a global middleware, and if you need to avoid this middleware for some routes, just insert into the public route group.
// config/accreditedApiKeys.php
return [
'api-1' => env('API_1_X_API_KEY'),
'api-2' => env('API_2_X_API_KEY'),
'api-3' => env('API_3_X_API_KEY'),
];
// bootstrap/app.php
$app->configure('accreditedApiKeys');
// Using in global mode
$app->middleware([
Logcomex\PhpUtils\Middlewares\AccreditedApiKeysMiddleware::class,
]);
// routes/api.php
$router->group(['prefix' => 'public',], function () use ($router) {
$router->get('test', 'Controller@test');// this route does not need x-infra-key validation
});
Providers
The idea of this package is provide some providers. For a better understanding: Lumen Providers
LogcomexLoggerProvider
You have to use this provider when you're using the Logger Facade.
// bootstrap/app.php
$app->register(Logcomex\MicroservicesCore\Providers\LogcomexLoggerProvider::class);
## Singletons
> They're a pack of Singleton classes.
#### TracerSingleton
> It is a class that provides the tracer value.
## Unit Tests Coverage
Master <br>
[](https://codecov.io/gh/comexio/php-utils)
## TODO
- [ ] HttpHelper Doc
- [ ] TokenHelper Doc
- [ ] Handlers Package Doc
- [ ] ExceptionHandler Doc
- [ ] Logs Package Doc
- [ ] RequestLog Doc
- [ ] Middlewares Package Doc
- [ ] AllowedHostsMiddleware Doc
- [ ] CorsMiddleware Doc
## Contributing
- Open an issue first to discuss potential changes/additions.
- Open a pull request, you need two approvals and tests need to pass Travis CI.
56 Dec 6, 2022
1 Nov 6, 2021
1 Nov 15, 2021
4 Dec 29, 2022
2 Dec 6, 2021
14 Jul 18, 2022
5 Apr 17, 2022
389 Nov 24, 2022
14 Nov 28, 2022
7 Aug 12, 2022
5 Mar 22, 2022
1 Apr 12, 2022
2 Nov 24, 2021
2 Dec 10, 2021
1 Jun 12, 2022
4 Sep 3, 2022
5 Dec 28, 2022
3 Jan 3, 2023
3 Mar 26, 2022