Skip to content

Commit 8d75bf6

Browse files
fabio-ivonafabio-ivona
committed
docs
1 parent bc7696c commit 8d75bf6

17 files changed

+340
-45
lines changed

‎.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
build
44
composer.lock
55
coverage
6-
docs
76
phpunit.xml
87
phpstan.neon
98
testbench.yaml

‎README.md‎

Lines changed: 2 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -79,37 +79,9 @@ if(AppFeature::multi_language->active()){
7979
}
8080
```
8181

82-
or be disabled
82+
An extensive documentation is available at
8383

84-
```php
85-
if(AppFeature::impersonate->inactive()){
86-
throw(new Exception("Impersonate feature is not enabled"));
87-
}
88-
```
89-
90-
or enforce it
91-
92-
```php
93-
94-
AppFeature::impersonate->enforce(); //throws "Feature [impersonate] is not enabled"
95-
96-
```
97-
98-
### Blade directives
99-
100-
In blade files, a feature can be checked with `@feature` directive:
101-
102-
```html
103-
104-
@feature(AppFeature::multi_language)
105-
<select name="language" xmlns="http://www.w3.org/1999/html">
106-
<option value="en">English</option>
107-
<option value="fr">French</option>
108-
<option value="it">Italian</option>
109-
</select>
110-
@endfeature
111-
112-
```
84+
https://docs.defstudio.it/enum-features
11385

11486
## Testing
11587

‎docs/0.index.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: 'Introduction'
3+
description: 'A simple trait to enable Laravel Pennant features using Enums'
4+
navigation.title: 'Introduction'
5+
---
6+
7+
# Laravel Enum Features
8+
9+
<a href="https://packagist.org/packages/defstudio/enum-features" target="_blank"><img style="display: inline-block; margin-top: 0.5em; margin-bottom: 0.5em" src="https://img.shields.io/packagist/v/defstudio/enum-features.svg?style=flat&cacheSeconds=3600" alt="Latest Version on Packagist"></a>
10+
<a href="https://github.com/defstudio/enum-features/actions/workflows/run-tests.yml" target="_blank"><img style="display: inline-block; margin-top: 0.5em; margin-bottom: 0.5em" src="https://img.shields.io/github/actions/workflow/status/defstudio/enum-features/run-tests.yml?branch=main&label=tests&cacheSeconds=3600&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABwAAAAcCAMAAABF0y+mAAABiVBMVEUAAAD/iPv9yP3Xm+j/mP//wfVj67Je6bP/h/pVx6p6175d57WQycf+iPn/iPrsnezArd3+t/qpvNJd6LP/jPpu6rv/lPr/kPpc57T/rvtc57Np6rj3oPl37cL/tfn/wv9d6brX//L/g/rYn+n/gvrWm+di6LX+jPrskfGWzMpt6bln4bdd57Jk6LWSycj+vPquwNVo6rde6bP7nvvYnup91b/+vfv/lvtc57OqvNTFs9//t/td57L9t/r/iPpd6LPapej/ovp26bxy67v9lfld6LJr4Ljwsvb/xv3/jv39zv1t6buG5cTDreH5ivlc5rJy676V4cxb57D/y/h50MOy4OCUxcVa77X/iPpe6LP/jP+pu9L8t///tvuQycfArNxp6LzArd151r7/i/9n4bb/j/9e6rT/ifr7ifrskvLYnuhi87tg8blg7bf/vv//lP+wxNtj9b3/qv//oP/+ivz/l/r8ifryn/fvlPTfpPDeofDKtujHtOWX1NF/4seC3cR82sFu7cBo5LiMwPMrAAAAWHRSTlMA/Wv8FAIC/dME/Wj+3tEG/Pv798G1oHRjS0k1LBsWDgsJ/v36+fTy8ezn4+Lh29XNzMzLysLAwLSwr66opJqakY+Ni4J7end0bGlpY11XU048KicmIR8fizl+vwAAAVdJREFUKM9tz2VXAlEQgOFBBURpkE67u7u7E1YFYQl1SbvrlztDiLvss+fc/fCemXMvAEhhKqU759P1rLoxUDUyEh9fPH0z7ALiVrEY+SSNtxNS2upouYv7hOL191aKVsZHUTgbnQPQgDkq4ctHdoQmTWmW4WFzlVUDVpNKXf2fWpWbZIwUq/hcmjWGYnSa1pZZjEoomrEdVAisD7CX6GEb40rqTODxCj21OjDOvjRV8l2jhudBDchg/FUbDIZCITzwQyH6a9+2AMDbm9GfltFnxgAdtQWUgQJl4VQq37uPcSnsfYZzav6Ew18fQ4fUYPM7Qn4uSiIdyx5saJ6T+/3+5KSltshicwI2UpfAKE/aoARTvnn7KMYMdlAUyWRSyHN2JeU42HlCi4TszTHcmuj3iMVdP5JzoyAWNzi6T3ZGrMFCliK3BAqRSC/B2+6IxvYYNcO+2Npfv+yFi10LfBUAAAAASUVORK5CYII=" alt="Tests"></a>
11+
<a href="https://github.com/defstudio/enum-features/actions/workflows/fix-php-code-style-issues.yml" target="_blank"><img style="display: inline-block; margin-top: 0.5em; margin-bottom: 0.5em" src="https://img.shields.io/github/actions/workflow/status/defstudio/enum-features/fix-php-code-style-issues.yml?branch=main&label=code%20style&cacheSeconds=3600" alt="Code Style"></a>
12+
<a href="https://github.com/defstudio/enum-features/actions/workflows/phpstan.yml" target="_blank"><img style="display: inline-block; margin-top: 0.5em; margin-bottom: 0.5em" src="https://img.shields.io/github/actions/workflow/status/defstudio/enum-features/phpstan.yml?branch=main&label=phpstan&cacheSeconds=3600" alt="Static Analysis"></a>
13+
<a href="https://packagist.org/packages/defstudio/enum-features" target="_blank"><img style="display: inline-block; margin-top: 0.5em; margin-bottom: 0.5em" src="https://img.shields.io/packagist/dt/defstudio/enum-features.svg?style=flat&cacheSeconds=3600" alt="Total Downloads"></a>
14+
<a href="https://packagist.org/packages/defstudio/enum-features" target="_blank"><img style="display: inline-block; margin-top: 0.5em; margin-bottom: 0.5em" src="https://img.shields.io/packagist/l/defstudio/enum-features?style=flat&cacheSeconds=3600" alt="License"></a>
15+
<a href="https://twitter.com/FabioIvona?ref_src=twsrc%5Etfw" target="_blank"><img style="display: inline-block; margin-top: 0.5em; margin-bottom: 0.5em" alt="Twitter Follow" src="https://img.shields.io/twitter/follow/FabioIvona?label=Follow&style=social"></a>
16+
17+
18+
#### A simple trait to enable Laravel Pennant features using Enums
19+
20+
21+
```php
22+
if(AppFeature::welcome_email->active()){
23+
Mail::to($newUser)->send(new WelcomeEmail($newUser));
24+
}
25+
```
26+
27+
[replace:full-source-code]
28+
29+
30+
[replace:powered-by]

‎docs/1.about-us.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
[replace:about-us]

‎docs/11.usage/1.feature-resolution.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: 'Feature Resolution'
3+
description: ''
4+
---
5+
6+
## Feature Resolution
7+
8+
On the first check for each scope, Laravel Pennant requires you to resolve if the feature is enabled for that scope. This can be done in your enum code:
9+
10+
### Single Catch-All Method
11+
12+
The resolve method can be overridden in order to return `true`/`false` for that user
13+
14+
```php
15+
use DefStudio\EnumFeatures\EnumFeatures;
16+
17+
enum AppFeature
18+
{
19+
use DefinesFeatures;
20+
21+
case multi_language;
22+
case impersonate;
23+
case welcome_email;
24+
25+
protected function resolve(Authenticatable $user = null) {
26+
match($this){
27+
case self::multi_language => true,
28+
case self::impersonate => $user->isAdmin(),
29+
default => false;
30+
}
31+
}
32+
}
33+
```
34+
35+
### A dedicated method for each feature
36+
37+
The `DefineFeatures` trait can check if a `resolve[FeatureName]` method exists, and will use it to determine if the feature is enabled.
38+
39+
> [!WARNING]
40+
> The feature is considered to be disabled if no `resolve[FeatureName]` method is defined for it
41+
42+
```php
43+
use DefStudio\EnumFeatures\EnumFeatures;
44+
45+
enum AppFeature
46+
{
47+
use DefinesFeatures;
48+
49+
case multi_language;
50+
case impersonate;
51+
case welcome_email;
52+
53+
protected function resolveImpersonate(Authenticatable $user = null){
54+
return $user->isSuperAdmin();
55+
}
56+
57+
protected function resolveWelcomeEmail(Authenticatable $user = null){
58+
return true;
59+
}
60+
}
61+
```
62+
63+
> [!NOTE]
64+
> the trait will search for any method with these patterns:
65+
> - `resolve[FeatureName]` (camel case)
66+
> - `resolve_[feature_name]` (snake case)

‎docs/11.usage/2.feature-check.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: 'Feature Check'
3+
description: ''
4+
---
5+
6+
## Feature Check
7+
8+
In code feature can be checked in multiple ways for the logged user:
9+
10+
### Check if enabled
11+
12+
```php
13+
if(AppFeature::multi_language->active()){
14+
//.. multi language specific code
15+
}
16+
```
17+
18+
### Check if disabled
19+
20+
```php
21+
if(AppFeature::multi_language->active()){
22+
//.. multi language specific code
23+
}
24+
```
25+
26+
### Enforced
27+
28+
```php
29+
30+
AppFeature::impersonate->enforce(); //throws a 403 exception if not active
31+
32+
```
33+
34+
## Feature Check for a given scope
35+
36+
Each check can be applied to a scope different from the logged user:
37+
38+
```php
39+
40+
$user = User::find(42);
41+
42+
if(AppFeature::multi_language->active($user)){
43+
//.. multi language specific code
44+
}
45+
46+
if(AppFeature::multi_language->active($user)){
47+
//.. multi language specific code
48+
}
49+
50+
AppFeature::impersonate->enforce($user); //throws a 403 exception if not active
51+
52+
```
53+
54+
## Multiple feature checks
55+
56+
This package can check for multiple feature at once as well:
57+
58+
### All Active
59+
60+
```php
61+
62+
if(AppFeature::areAllActive([AppFeature::multi_language, AppFeature::welcome_email])){
63+
//..
64+
}
65+
66+
```
67+
68+
### Some Active
69+
70+
```php
71+
72+
if(AppFeature::someAreActive([AppFeature::multi_language, AppFeature::welcome_email])){
73+
//..
74+
}
75+
76+
```
77+
78+
### All Inactive
79+
80+
```php
81+
82+
if(AppFeature::areAllInactive([AppFeature::multi_language, AppFeature::welcome_email])){
83+
//..
84+
}
85+
86+
```
87+
88+
### Some Inactive
89+
90+
```php
91+
92+
if(AppFeature::someAreInactive([AppFeature::multi_language, AppFeature::welcome_email])){
93+
//..
94+
}
95+
96+
```

‎docs/11.usage/3.updating-values.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: 'Updating Values'
3+
description: ''
4+
---
5+
6+
## Updating Values
7+
8+
Laravel Pennant stores the value resolved for a given scope, in order to change the stored value this package offers some useful methods:
9+
10+
### Activate a feature
11+
12+
```php
13+
AppFeature::multi_language->activate();
14+
15+
//also for a given scope
16+
AppFeature::multi_language->activate($user);
17+
```
18+
19+
### Deactivate a feature
20+
21+
```php
22+
AppFeature::multi_language->deactivate();
23+
24+
//also for a given scope
25+
AppFeature::multi_language->deactivate($user);
26+
```
27+
28+
### Forget stored value
29+
30+
```php
31+
AppFeature::multi_language->forget();
32+
33+
//also for a given scope
34+
AppFeature::multi_language->forget($user);
35+
```
36+
37+
### Forget for all scopes
38+
39+
```php
40+
AppFeature::multi_language->purge();
41+
```

‎docs/11.usage/4.blade-directive.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: 'Blade Directive'
3+
description: ''
4+
---
5+
6+
## Blade Directive
7+
8+
To help checking features in blade code, this package offers a `@feature` directive
9+
10+
```html
11+
12+
@feature(AppFeature::multi_language)
13+
<select name="language" xmlns="http://www.w3.org/1999/html">
14+
<option value="en">English</option>
15+
<option value="fr">French</option>
16+
<option value="it">Italian</option>
17+
</select>
18+
@endfeature
19+
20+
```

‎docs/11.usage/5.middleware.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: 'Middleware'
3+
description: ''
4+
---
5+
6+
## Middleware
7+
8+
Features can be enforced using Laravel Pennants [middlewares](https://laravel.com/docs/11.x/pennant#middleware)
9+
10+
```php
11+
12+
Route::get('/users/{user}/impersonate', function(){
13+
// ...
14+
})->middleware(AppFeature::impersonate->middleware());
15+
16+
```

‎docs/17.community/1.contributing.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
[replace:contributing]

0 commit comments

Comments
 (0)