Laravel AT Protocol Client (alpha & unstable)
Document scope authorization features in README
+102
+102
README.md
+102
README.md
···
844
844
});
845
845
```
846
846
847
+
## Scope Authorization
848
+
849
+
The package provides Laravel-native authorization features for checking ATP OAuth scopes, similar to Laravel's Gate/Policy system.
850
+
851
+
### Setup
852
+
853
+
Have your User model implement the `HasAtpSession` interface:
854
+
855
+
```php
856
+
use SocialDept\AtpClient\Contracts\HasAtpSession;
857
+
858
+
class User extends Authenticatable implements HasAtpSession
859
+
{
860
+
public function getAtpDid(): ?string
861
+
{
862
+
return $this->atp_did; // or however you store the DID
863
+
}
864
+
}
865
+
```
866
+
867
+
### Route Middleware
868
+
869
+
Protect routes by requiring specific scopes. Uses AND logic (all listed scopes required):
870
+
871
+
```php
872
+
use Illuminate\Support\Facades\Route;
873
+
874
+
// Requires transition:generic scope
875
+
Route::post('/posts', [PostController::class, 'store'])
876
+
->middleware('atp.scope:transition:generic');
877
+
878
+
// Requires BOTH scopes
879
+
Route::post('/dm', [MessageController::class, 'store'])
880
+
->middleware('atp.scope:transition:generic,transition:chat.bsky');
881
+
```
882
+
883
+
### AtpScope Facade
884
+
885
+
Use the `AtpScope` facade for programmatic scope checks:
886
+
887
+
```php
888
+
use SocialDept\AtpClient\Facades\AtpScope;
889
+
890
+
// Check if user has a scope
891
+
if (AtpScope::can('transition:generic')) {
892
+
// ...
893
+
}
894
+
895
+
// Check if user has any of the scopes
896
+
if (AtpScope::canAny(['transition:generic', 'transition:chat.bsky'])) {
897
+
// ...
898
+
}
899
+
900
+
// Check if user has all scopes
901
+
if (AtpScope::canAll(['atproto', 'transition:generic'])) {
902
+
// ...
903
+
}
904
+
905
+
// Authorize or fail (throws/aborts based on config)
906
+
AtpScope::authorize('transition:generic');
907
+
908
+
// Check for a specific user
909
+
AtpScope::forUser($did)->authorize('transition:generic');
910
+
911
+
// Get all granted scopes
912
+
$scopes = AtpScope::granted();
913
+
```
914
+
915
+
### Session Helper Methods
916
+
917
+
The Session class also has convenience methods:
918
+
919
+
```php
920
+
$session = Atp::as($did)->session();
921
+
922
+
$session->can('transition:generic');
923
+
$session->canAny(['transition:generic', 'transition:chat.bsky']);
924
+
$session->canAll(['atproto', 'transition:generic']);
925
+
$session->cannot('transition:chat.bsky');
926
+
```
927
+
928
+
### Configuration
929
+
930
+
Configure authorization failure behavior in `config/client.php`:
931
+
932
+
```php
933
+
'scope_authorization' => [
934
+
// What happens when scope check fails: 'abort', 'redirect', or 'exception'
935
+
'failure_action' => ScopeAuthorizationFailure::Abort,
936
+
937
+
// Redirect URL when failure_action is 'redirect'
938
+
'redirect_to' => '/login',
939
+
],
940
+
```
941
+
942
+
Or via environment variables:
943
+
944
+
```env
945
+
ATP_SCOPE_FAILURE_ACTION=abort
946
+
ATP_SCOPE_REDIRECT=/login
947
+
```
948
+
847
949
## Available Commands
848
950
849
951
```bash