Skip to content

Commit a5b5524

Browse files
lisachenkolisachenko
committed
Added a README file for easy start with this bridge
1 parent 82cd1c4 commit a5b5524

File tree

1 file changed

+223
-0
lines changed

1 file changed

+223
-0
lines changed

Diff for: ‎README.md

+223
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
GoAopBridge
2+
==============
3+
4+
[![GitHub release](https://img.shields.io/github/release/goaop/goaop-laravel-bridge.svg)](https://github.com/goaop/goaop-laravel-bridge/releases/latest)
5+
[![Minimum PHP Version](http://img.shields.io/badge/php-%3E%3D%205.5-8892BF.svg)](https://php.net/)
6+
[![License](https://img.shields.io/packagist/l/goaop/goaop-laravel-bridge.svg)](https://packagist.org/packages/goaop/goaop-laravel-bridge)
7+
8+
The GoAopBridge adds support for Aspect-Oriented Programming via Go! AOP Framework for Laravel5 applications.
9+
10+
Overview
11+
--------
12+
13+
Aspect-Oriented Paradigm allows to extend the standard Object-Oriented Paradigm with special instruments for effective solving of cross-cutting concerns in your application. This code is typically present everywhere in your application (for example, logging, caching, monitoring, etc) and there is no easy way to fix this without AOP.
14+
15+
AOP defines new instruments for developers, they are:
16+
17+
* Joinpoint - place in your code that can be used for interception, for example, execution of single public method or accessing of single object property.
18+
* Pointcut is a list of joinpoints defined with a special regexp-like expression for your source code, for example, all public and protected methods in the concrete class or namespace.
19+
* Advice is an additional callback that will be called before, after or around concrete joinpoint. For PHP each advice is represented as a `\Closure` instance, wrapped into the interceptor object.
20+
* Aspect is a special class that combines pointcuts and advices together, each pointcut is defined as an annotation and each advice is a method inside this aspect.
21+
22+
You can read more about AOP in different sources, there are good articles for Java language and they can be applied for PHP too, because it's general paradigm.
23+
24+
Installation
25+
------------
26+
27+
GoAopBridge can be easily installed with composer. Just ask a composer to download the bundle with dependencies by running the command:
28+
29+
```bash
30+
$ composer require goaop/goaop-laravel-bridge
31+
```
32+
33+
Add the `Go\Laravel\GoAopBridge\GoAopServiceProvider` to your config/app.php `providers` array:
34+
```php
35+
// config/app.php
36+
37+
'providers' => [
38+
// Go! Aspect Service Provider
39+
Go\Laravel\GoAopBridge\GoAopServiceProvider::class,
40+
```
41+
Make sure that this service provider is the **first item** in this list. This is required for the AOP engine to work correctly.
42+
43+
Configuration
44+
-------------
45+
46+
The default configuration in the `config/go_aop.php` file. Copy this file to your own config directory to modify the values. You can also publish the config using this command:
47+
48+
```bash
49+
./artisan vendor:publish --provider="Go\Laravel\GoAopBridge\GoAopServiceProvider"
50+
```
51+
52+
Configuration can be used for additional tuning of AOP kernel and source code whitelistsing/blacklisting.
53+
```php
54+
// config/go_aop.php
55+
56+
return [
57+
/*
58+
|--------------------------------------------------------------------------
59+
| AOP Debug Mode
60+
|--------------------------------------------------------------------------
61+
|
62+
| When AOP is in debug mode, then breakpoints in the original source code
63+
| will work. Also engine will refresh cache files if the original files were
64+
| changed.
65+
| For production mode, no extra filemtime checks and better integration with opcache
66+
|
67+
*/
68+
'debug' => env('APP_DEBUG', false),
69+
70+
/*
71+
|--------------------------------------------------------------------------
72+
| Application root directory
73+
|--------------------------------------------------------------------------
74+
|
75+
| AOP will be applied only to the files in this directory, change it to app_path()
76+
| if needed
77+
*/
78+
'appDir' => base_path(),
79+
80+
/*
81+
|--------------------------------------------------------------------------
82+
| AOP cache directory
83+
|--------------------------------------------------------------------------
84+
|
85+
| AOP engine will put all transformed files and caches in that directory
86+
*/
87+
'cacheDir' => storage_path('app/aspect'),
88+
89+
/*
90+
|--------------------------------------------------------------------------
91+
| Cache file mode
92+
|--------------------------------------------------------------------------
93+
|
94+
| If configured then will be used as cache file mode for chmod
95+
*/
96+
'cacheFileMode' => null,
97+
98+
/*
99+
|--------------------------------------------------------------------------
100+
| Controls miscellaneous features of AOP engine
101+
|--------------------------------------------------------------------------
102+
|
103+
| See \Go\Aop\Features enumeration for bit mask
104+
*/
105+
'features' => 0,
106+
107+
/*
108+
|--------------------------------------------------------------------------
109+
| White list of directories
110+
|--------------------------------------------------------------------------
111+
|
112+
| AOP will check this list to apply an AOP to selected directories only,
113+
| leave it empty if you want AOP to be applied to all files in the appDir
114+
*/
115+
'includePaths' => [
116+
app_path()
117+
],
118+
119+
/*
120+
|--------------------------------------------------------------------------
121+
| Black list of directories
122+
|--------------------------------------------------------------------------
123+
|
124+
| AOP will check this list to disable AOP for selected directories
125+
*/
126+
'excludePaths' => [],
127+
128+
/*
129+
|--------------------------------------------------------------------------
130+
| AOP container class
131+
|--------------------------------------------------------------------------
132+
|
133+
| This option can be useful for extension and fine-tuning of services
134+
*/
135+
'containerClass' => GoAspectContainer::class,
136+
]
137+
```
138+
139+
Defining new aspects
140+
--------------------
141+
142+
Aspects are services in the Laravel application and loaded into the AOP container with the help of service provider that collects all services tagged with `goaop.aspect` tag in the container. Here is an example how to implement a logging aspect that will log information about public method invocations in the app/ directory.
143+
144+
145+
Definition of aspect class with pointuct and logging advice
146+
```php
147+
<?php
148+
149+
namespace App\Aspect;
150+
151+
use Go\Aop\Aspect;
152+
use Go\Aop\Intercept\MethodInvocation;
153+
use Go\Lang\Annotation\Before;
154+
use Psr\Log\LoggerInterface;
155+
156+
/**
157+
* Application logging aspect
158+
*/
159+
class LoggingAspect implements Aspect
160+
{
161+
/**
162+
* @var LoggerInterface
163+
*/
164+
private $logger;
165+
166+
public function __construct(LoggerInterface $logger)
167+
{
168+
$this->logger = $logger;
169+
}
170+
171+
/**
172+
* Writes a log info before method execution
173+
*
174+
* @param MethodInvocation $invocation
175+
* @Before("execution(public **->*(*))")
176+
*/
177+
public function beforeMethod(MethodInvocation $invocation)
178+
{
179+
$this->logger->info($invocation, $invocation->getArguments());
180+
}
181+
}
182+
```
183+
184+
To register all application aspects in the container, create a service provider (or use an existing one)
185+
```bash
186+
./artisan make:provider AopServiceProvider
187+
```
188+
189+
Inside `register()` method for this service provider, add declaration of aspect and tag it with `goaop.aspect` tag:
190+
191+
```php
192+
193+
namespace App\Providers;
194+
195+
use App\Aspect\LoggingAspect;
196+
use Illuminate\Contracts\Foundation\Application;
197+
use Illuminate\Support\ServiceProvider;
198+
use Psr\Log\LoggerInterface;
199+
200+
class AopServiceProvider extends ServiceProvider
201+
{
202+
203+
/**
204+
* Register the application services.
205+
*
206+
* @return void
207+
*/
208+
public function register()
209+
{
210+
$this->app->singleton(LoggingAspect::class, function (Application $app) {
211+
return new LoggingAspect($app->make(LoggerInterface::class));
212+
});
213+
214+
$this->app->tag([LoggingAspect::class], 'goaop.aspect');
215+
}
216+
```
217+
218+
Don't forget to add this service provider into your `config/app.php` service providers list!
219+
220+
License
221+
-------
222+
223+
This bridge is under the MIT license. See the complete LICENSE in the root directory

0 commit comments

Comments
 (0)