4 Commits

Author SHA1 Message Date
d447a88430 add mode
Signed-off-by: Maurice Preuß (envoyr) <hello@envoyr.com>
2025-04-29 21:33:02 +02:00
d9a330222b update billable
Signed-off-by: Maurice Preuß (envoyr) <hello@envoyr.com>
2025-04-28 17:26:02 +02:00
21946e3a22 update docs
Signed-off-by: Maurice Preuß (envoyr) <hello@envoyr.com>
2025-04-28 05:32:44 +02:00
1b96b87e1d refactored code
Signed-off-by: Maurice Preuß (envoyr) <hello@envoyr.com>
2025-04-28 05:27:06 +02:00
12 changed files with 363 additions and 98 deletions

113
README.md
View File

@@ -9,13 +9,11 @@ PHP Anikeen ID API Client for Laravel 11+
## Table of contents
1. [Installation](#installation)
2. [Event Listener](#event-listener)
3. [Configuration](#configuration)
4. [Implementing Auth](#implementing-auth)
5. [General](#general)
6. [Examples](#examples)
7. [Documentation](#documentation)
8. [Development](#Development)
2. [Configuration](#configuration)
3. [General](#general)
4. [Examples](#examples)
5. [Documentation](#documentation)
6. [Development](#Development)
## Installation
@@ -23,19 +21,9 @@ PHP Anikeen ID API Client for Laravel 11+
composer require anikeen/id
```
## Event Listener
In Laravel 11, the default EventServiceProvider provider was removed. Instead, add the listener using the listen method on the Event facade, in your `AppServiceProvider`
```
Event::listen(function (\SocialiteProviders\Manager\SocialiteWasCalled $event) {
$event->extendSocialite('anikeen-id', \Anikeen\Id\Socialite\Provider::class);
});
```
## Configuration
Add environmental variables to your `.env`
Add environmental variables to your `.env` file:
```
ANIKEEN_ID_KEY=
@@ -43,12 +31,19 @@ ANIKEEN_ID_SECRET=
ANIKEEN_ID_CALLBACK_URL=http://localhost/auth/callback
```
To switch from `production` to `staging` use following variable:
```
ANIKEEN_ID_MODE=staging
```
You will need to add an entry to the services configuration file so that after config files are cached for usage in production environment (Laravel command `artisan config:cache`) all config is still available.
**Add to `config/services.php`:**
Add to `config/services.php` file:
```php
'anikeen' => [
'mode' => env('ANIKEEN_ID_MODE'),
'client_id' => env('ANIKEEN_ID_KEY'),
'client_secret' => env('ANIKEEN_ID_SECRET'),
'redirect' => env('ANIKEEN_ID_CALLBACK_URL'),
@@ -56,13 +51,63 @@ You will need to add an entry to the services configuration file so that after c
],
```
### Event Listener
In Laravel 11, the default EventServiceProvider provider was removed. Instead, add the listener using the listen method on the Event facade, in your `AppServiceProvider` boot method:
```php
$middleware->web(append: [
\Anikeen\Id\Http\Middleware\CreateFreshApiToken::class,
]);
public function boot(): void
{
Event::listen(function (\SocialiteProviders\Manager\SocialiteWasCalled $event) {
$event->extendSocialite('anikeen-id', \Anikeen\Id\Socialite\Provider::class);
});
}
```
## Implementing Auth
### Registering Middleware
Append it to the global middleware stack in your application's `bootstrap/app.php` file:
```php
->withMiddleware(function (Middleware $middleware) {
$middleware->web(append: [
\Anikeen\Id\Http\Middleware\CreateFreshApiToken::class,
]);
})
```
### Implementing Billable
To implement the `Billable` trait, you need to add the `Billable` trait to your user model.
```php
use Anikeen\Id\Billable;
class User extends Authenticatable
{
use Billable;
// Your model code...
}
```
then, you can use the `Billable` trait methods in your user model.
### Change the default access token / refresh token field name
If you access / refresh token fields differs from the default `anikeen_id_access_token` / `anikeen_id_refresh_token`, you can specify the field name in the `AppServiceProvider` boot method:
```php
use Anikeen\Id\AnikeenId;
public function boot(): void
{
AnikeenId::useAccessTokenField('anikeen_id_access_token');
AnikeenId::useRefreshTokenField('anikeen_id_refresh_token');
}
```
### Implementing Auth
This method should typically be called in the `boot` method of your `AuthServiceProvider` class:
@@ -71,12 +116,7 @@ use Anikeen\Id\AnikeenId;
use Anikeen\Id\Providers\AnikeenIdSsoUserProvider;
use Illuminate\Http\Request;
/**
* Register any authentication / authorization services.
*
* @return void
*/
public function boot()
public function boot(): void
{
Auth::provider('sso-users', function ($app, array $config) {
return new AnikeenIdSsoUserProvider(
@@ -84,7 +124,6 @@ public function boot()
$app->make(Request::class),
$config['model'],
$config['fields'] ?? [],
$config['access_token_field'] ?? null
);
});
}
@@ -119,7 +158,6 @@ reference the provider in the `providers` configuration of your `auth.php` confi
'driver' => 'sso-users',
'model' => App\Models\User::class,
'fields' => ['first_name', 'last_name', 'email'],
'access_token_field' => 'sso_access_token',
],
],
```
@@ -272,6 +310,16 @@ public function isEmailExisting(string $email): Result
## Billable
### ManagesAddresses
```php
public function addresses(): Result
public function createAddress(array $attributes = []): Result
public function address(string $addressId): Result
public function updateAddress(string $addressId, array $attributes = []): Result
public function deleteAddress(string $addressId): Result
```
### ManagesBalance
```php
@@ -285,7 +333,7 @@ public function charge(float $amount, string $paymentMethodId, array $options =
```php
public function invoices(): Result
public function invoice(string $invoiceId): Result
public function getInvoiceDownloadUrl(string $invoiceId): string
public function getInvoiceTemporaryUrl(string $invoiceId): string
```
### ManagesOrders
@@ -325,6 +373,7 @@ public function createSubscription(array $attributes): Result
public function checkoutSubscription(string $subscriptionId): Result
public function revokeSubscription(string $subscriptionId): Result
public function resumeSubscription(string $subscriptionId): Result
public function deleteSubscription(string $subscriptionId): Result
```
### ManagesTaxation

View File

@@ -9,13 +9,11 @@ PHP Anikeen ID API Client for Laravel 11+
## Table of contents
1. [Installation](#installation)
2. [Event Listener](#event-listener)
3. [Configuration](#configuration)
4. [Implementing Auth](#implementing-auth)
5. [General](#general)
6. [Examples](#examples)
7. [Documentation](#documentation)
8. [Development](#Development)
2. [Configuration](#configuration)
3. [General](#general)
4. [Examples](#examples)
5. [Documentation](#documentation)
6. [Development](#Development)
## Installation
@@ -23,19 +21,9 @@ PHP Anikeen ID API Client for Laravel 11+
composer require anikeen/id
```
## Event Listener
In Laravel 11, the default EventServiceProvider provider was removed. Instead, add the listener using the listen method on the Event facade, in your `AppServiceProvider`
```
Event::listen(function (\SocialiteProviders\Manager\SocialiteWasCalled $event) {
$event->extendSocialite('anikeen-id', \Anikeen\Id\Socialite\Provider::class);
});
```
## Configuration
Add environmental variables to your `.env`
Add environmental variables to your `.env` file:
```
ANIKEEN_ID_KEY=
@@ -43,12 +31,19 @@ ANIKEEN_ID_SECRET=
ANIKEEN_ID_CALLBACK_URL=http://localhost/auth/callback
```
To switch from `production` to `staging` use following variable:
```
ANIKEEN_ID_MODE=staging
```
You will need to add an entry to the services configuration file so that after config files are cached for usage in production environment (Laravel command `artisan config:cache`) all config is still available.
**Add to `config/services.php`:**
Add to `config/services.php` file:
```php
'anikeen' => [
'mode' => env('ANIKEEN_ID_MODE'),
'client_id' => env('ANIKEEN_ID_KEY'),
'client_secret' => env('ANIKEEN_ID_SECRET'),
'redirect' => env('ANIKEEN_ID_CALLBACK_URL'),
@@ -56,13 +51,63 @@ You will need to add an entry to the services configuration file so that after c
],
```
### Event Listener
In Laravel 11, the default EventServiceProvider provider was removed. Instead, add the listener using the listen method on the Event facade, in your `AppServiceProvider` boot method:
```php
$middleware->web(append: [
\Anikeen\Id\Http\Middleware\CreateFreshApiToken::class,
]);
public function boot(): void
{
Event::listen(function (\SocialiteProviders\Manager\SocialiteWasCalled $event) {
$event->extendSocialite('anikeen-id', \Anikeen\Id\Socialite\Provider::class);
});
}
```
## Implementing Auth
### Registering Middleware
Append it to the global middleware stack in your application's `bootstrap/app.php` file:
```php
->withMiddleware(function (Middleware $middleware) {
$middleware->web(append: [
\Anikeen\Id\Http\Middleware\CreateFreshApiToken::class,
]);
})
```
### Implementing Billable
To implement the `Billable` trait, you need to add the `Billable` trait to your user model.
```php
use Anikeen\Id\Billable;
class User extends Authenticatable
{
use Billable;
// Your model code...
}
```
then, you can use the `Billable` trait methods in your user model.
### Change the default access token / refresh token field name
If you access / refresh token fields differs from the default `anikeen_id_access_token` / `anikeen_id_refresh_token`, you can specify the field name in the `AppServiceProvider` boot method:
```php
use Anikeen\Id\AnikeenId;
public function boot(): void
{
AnikeenId::useAccessTokenField('anikeen_id_access_token');
AnikeenId::useRefreshTokenField('anikeen_id_refresh_token');
}
```
### Implementing Auth
This method should typically be called in the `boot` method of your `AuthServiceProvider` class:
@@ -71,12 +116,7 @@ use Anikeen\Id\AnikeenId;
use Anikeen\Id\Providers\AnikeenIdSsoUserProvider;
use Illuminate\Http\Request;
/**
* Register any authentication / authorization services.
*
* @return void
*/
public function boot()
public function boot(): void
{
Auth::provider('sso-users', function ($app, array $config) {
return new AnikeenIdSsoUserProvider(
@@ -84,7 +124,6 @@ public function boot()
$app->make(Request::class),
$config['model'],
$config['fields'] ?? [],
$config['access_token_field'] ?? null
);
});
}
@@ -119,7 +158,6 @@ reference the provider in the `providers` configuration of your `auth.php` confi
'driver' => 'sso-users',
'model' => App\Models\User::class,
'fields' => ['first_name', 'last_name', 'email'],
'access_token_field' => 'sso_access_token',
],
],
```

View File

@@ -52,14 +52,19 @@ class AnikeenId
private static string $baseUrl = 'https://id.anikeen.com/api/';
/**
* The key for the access token.
* The staging base URL for Anikeen ID API.
*/
private static string $accessTokenKey = 'anikeen_id_token';
private static string $stagingBaseUrl = 'https://staging.id.anikeen.com/api/';
/**
* The key for the access token.
*/
private static string $refreshTokenKey = 'anikeen_id_refresh_token';
private static string $accessTokenField = 'anikeen_id_access_token';
/**
* The key for the access token.
*/
private static string $refreshTokenField = 'anikeen_id_refresh_token';
/**
* Guzzle is used to make http requests.
@@ -105,6 +110,9 @@ class AnikeenId
if ($redirectUri = config('services.anikeen.redirect')) {
$this->setRedirectUri($redirectUri);
}
if (config('services.anikeen.mode') === 'staging') {
self::setBaseUrl(self::$stagingBaseUrl);
}
if ($baseUrl = config('services.anikeen.base_url')) {
self::setBaseUrl($baseUrl);
}
@@ -123,24 +131,24 @@ class AnikeenId
self::$baseUrl = $baseUrl;
}
public static function useAccessTokenKey(string $accessTokenKey): void
public static function useAccessTokenField(string $accessTokenField): void
{
self::$accessTokenKey = $accessTokenKey;
self::$accessTokenField = $accessTokenField;
}
public static function getAccessTokenKey(): string
public static function getAccessTokenField(): string
{
return self::$accessTokenKey;
return self::$accessTokenField;
}
public static function useRefreshTokenKey(string $refreshTokenKey): void
public static function useRefreshTokenField(string $refreshTokenField): void
{
self::$refreshTokenKey = $refreshTokenKey;
self::$refreshTokenField = $refreshTokenField;
}
public static function getRefreshTokenKey(): string
public static function getRefreshTokenField(): string
{
return self::$refreshTokenKey;
return self::$refreshTokenField;
}
/**

View File

@@ -62,4 +62,9 @@ class UserProvider implements Base
{
return $this->providerName;
}
public function rehashPasswordIfRequired(Authenticatable $user, #[\SensitiveParameter] array $credentials, bool $force = false)
{
// TODO: Implement rehashPasswordIfRequired() method.
}
}

View File

@@ -3,6 +3,7 @@
namespace Anikeen\Id;
use Anikeen\Id\ApiOperations\Request;
use Anikeen\Id\Concerns\ManagesAddresses;
use Anikeen\Id\Concerns\ManagesBalance;
use Anikeen\Id\Concerns\ManagesInvoices;
use Anikeen\Id\Concerns\ManagesOrders;
@@ -17,6 +18,7 @@ use stdClass;
trait Billable
{
use ManagesAddresses;
use ManagesBalance;
use ManagesInvoices;
use ManagesOrders;
@@ -51,7 +53,7 @@ trait Billable
protected function request(string $method, string $path, null|array $payload = null, array $parameters = [], Paginator $paginator = null): Result
{
$anikeenId = new AnikeenId();
$anikeenId->withToken($this->{AnikeenId::getAccessTokenKey()});
$anikeenId->withToken($this->{AnikeenId::getAccessTokenField()});
return $anikeenId->request($method, $path, $payload, $parameters, $paginator);
}

View File

@@ -0,0 +1,132 @@
<?php
namespace Anikeen\Id\Concerns;
use Anikeen\Id\ApiOperations\Request;
use Anikeen\Id\Exceptions\RequestRequiresClientIdException;
use Anikeen\Id\Result;
use GuzzleHttp\Exception\GuzzleException;
trait ManagesAddresses
{
use Request;
/**
* Get addresses from the current user.
*
* @throws RequestRequiresClientIdException
* @throws GuzzleException
*/
public function addresses(): Result
{
return $this->request('GET', 'v1/addresses');
}
/**
* Creates a new address for the current user.
*
* @param array{
* company_name: null|string,
* first_name: string,
* last_name: string,
* address: string,
* address_2: null|string,
* house_number: null|string,
* postal_code: string,
* city: string,
* state: null|string,
* country_iso: string,
* phone_number: null|string,
* email: null|string,
* primary: bool,
* primary_billing_address: bool
* } $attributes The address data:
*   - company_name: Company name (optional)
*   - first_name: First name
*   - last_name: Last name
*   - address: Address line 1 (e.g. street address, P.O. Box, etc.)
*   - address_2: Address line 2 (optional, e.g. apartment number, c/o, etc.)
*   - house_number: House number (optional)
*   - postal_code: Postal code
*   - city: City
*   - state: State (optional, e.g. province, region, etc.)
*   - country_iso: Country ISO code (e.g. US, CA, etc.)
*   - phone_number: Phone number (optional)
*   - email: Email address (optional, e.g. for delivery notifications)
*   - primary: Whether this address should be the primary address (optional)
*   - primary_billing_address: Whether this address should be the primary billing address (optional)
* @throws RequestRequiresClientIdException
* @throws GuzzleException
*/
public function createAddress(array $attributes = []): Result
{
return $this->request('POST', 'v1/addresses', $attributes);
}
/**
* Get given address from the current user.
*
* @throws RequestRequiresClientIdException
* @throws GuzzleException
*/
public function address(string $addressId): Result
{
return $this->request('GET', sprintf('v1/addresses/%s', $addressId));
}
/**
* Update given address from the current user.
*
* VAT is calculated based on the billing address and shown in the address response.
*
* @param string $addressId The address ID.
* @param array{
* company_name: null|string,
* first_name: string,
* last_name: string,
* address_2: null|string,
* address: string,
* house_number: null|string,
* postal_code: string,
* city: string,
* state: null|string,
* country_iso: string,
* phone_number: null|string,
* email: null|string,
* primary: bool,
* primary_billing_address: bool
* } $attributes The address data:
* - company_name: Company name (optional)
* - first_name: First name (required when set)
* - last_name: Last name (required when set)
* - address: Address line 1 (e.g. street address, P.O. Box, etc.)
* - address_2: Address line 2 (optional, e.g. apartment number, c/o, etc.)
* - house_number: House number (optional)
* - postal_code: Postal code (required when set)
* - city: City (required when set)
* - state: State (optional, e.g. province, region, etc.)
* - country_iso: Country ISO code (required when set, e.g. US, CA, etc.)
* - phone_number: Phone number (optional)
* - email: Email address (optional, e.g. for delivery notifications)
* - primary: Whether this address should be the primary address (optional)
* - primary_billing_address: Whether this address should be the primary billing address (optional)
* @throws RequestRequiresClientIdException
* @throws GuzzleException
*/
public function updateAddress(string $addressId, array $attributes = []): Result
{
return $this->request('PUT', sprintf('v1/addresses/%s', $addressId), $attributes);
}
/**
* Delete given address from the current user.
*
* @param string $addressId The address ID.
* @throws RequestRequiresClientIdException
* @throws GuzzleException
*/
public function deleteAddress(string $addressId): Result
{
return $this->request('DELETE', sprintf('v1/addresses/%s', $addressId));
}
}

View File

@@ -35,14 +35,14 @@ trait ManagesInvoices
}
/**
* Get download url from given invoice.
* Get temporary download url from given invoice.
*
* @param string $invoiceId The invoice ID
* @throws RequestRequiresClientIdException
* @throws GuzzleException
*/
public function getInvoiceDownloadUrl(string $invoiceId): string
public function getInvoiceTemporaryUrl(string $invoiceId): string
{
return $this->request('PUT', sprintf('v1/invoices/%s', $invoiceId))->data->download_url;
return $this->request('PUT', sprintf('v1/invoices/%s', $invoiceId))->data->temporary_url;
}
}

View File

@@ -27,6 +27,11 @@ trait ManagesOrders
*
* VAT is calculated based on the billing address and shown in the order response.
*
* The billing and shipping addresses are each persisted as standalone Address entities
* in the database, but are also embedded (deep-copied) into the Order object itself
* rather than merely referenced. This guarantees that the order retains its own snapshot
* of both addresses for future reference.
*
* @param array{
* billing_address: array{
* company_name: null|string,
@@ -92,6 +97,11 @@ trait ManagesOrders
*
* VAT is calculated based on the billing address and shown in the order response.
*
* The billing and shipping addresses are each persisted as standalone Address entities
* in the database, but are also embedded (deep-copied) into the Order object itself
* rather than merely referenced. This guarantees that the order retains its own snapshot
* of both addresses for future reference.
*
* @param string $orderId The order ID.
* @param array{
* billing_address: array{

View File

@@ -41,7 +41,7 @@ trait ManagesPaymentMethods
*/
public function hasDefaultPaymentMethod(): bool
{
return $this->defaultPaymentMethod()->count() > 0;
return (bool)$this->defaultPaymentMethod()->data;
}
/**
@@ -65,7 +65,7 @@ trait ManagesPaymentMethods
*/
public function billingPortalUrl(string $returnUrl, array $options): string
{
return $this->request('POST', 'v1/stripe/billing-portal', [
return $this->request('POST', 'v1/billing/portal', [
'return_url' => $returnUrl,
'options' => $options,
])->data->url;

View File

@@ -100,4 +100,16 @@ trait ManagesSubscriptions
{
return $this->request('PUT', sprintf('v1/subscriptions/%s/resume', $subscriptionId));
}
/**
* Delete a given subscription from the current user.
*
* @param string $subscriptionId The subscription ID.
* @throws RequestRequiresClientIdException
* @throws GuzzleException
*/
public function deleteSubscription(string $subscriptionId): Result
{
return $this->request('DELETE', sprintf('v1/subscriptions/%s', $subscriptionId));
}
}

View File

@@ -13,28 +13,19 @@ use Illuminate\Support\Arr;
class AnikeenIdSsoUserProvider implements UserProvider
{
private AnikeenId $anikeenId;
private ?string $accessTokenField = null;
private array $fields;
private string $model;
private Request $request;
public function __construct(
AnikeenId $anikeenId,
Request $request,
string $model,
array $fields,
?string $accessTokenField = null
private AnikeenId $anikeenId,
private Request $request,
private string $model,
private array $fields
)
{
$this->request = $request;
$this->model = $model;
$this->fields = $fields;
$this->accessTokenField = $accessTokenField;
$this->anikeenId = $anikeenId;
$this->accessTokenField = AnikeenId::getAccessTokenField();
}
public function retrieveById(mixed $identifier): Builder|Model|null
public function retrieveById(mixed $identifier): ?Authenticatable
{
$model = $this->createModel();
$token = $this->request->bearerToken();
@@ -114,4 +105,9 @@ class AnikeenIdSsoUserProvider implements UserProvider
{
return false;
}
public function rehashPasswordIfRequired(Authenticatable $user, #[\SensitiveParameter] array $credentials, bool $force = false)
{
// TODO: Implement rehashPasswordIfRequired() method.
}
}

View File

@@ -4,6 +4,7 @@ namespace Anikeen\Id\Socialite;
use Anikeen\Id\Enums\Scope;
use GuzzleHttp\Exception\GuzzleException;
use Illuminate\Http\Request;
use Illuminate\Support\Arr;
use Laravel\Socialite\Two\ProviderInterface;
use SocialiteProviders\Manager\OAuth2\AbstractProvider;
@@ -26,13 +27,25 @@ class Provider extends AbstractProvider implements ProviderInterface
*/
protected $scopeSeparator = ' ';
/**
* Get the base URL for the API.
*/
protected function getBaseUrl(): string
{
$mode = $this->config['mode'] ?? 'production';
return $mode === 'staging'
? 'https://staging.id.anikeen.com'
: 'https://id.anikeen.com';
}
/**
* {@inheritdoc}
*/
protected function getAuthUrl($state): string
{
return $this->buildAuthUrlFromBase(
'https://id.anikeen.com/oauth/authorize', $state
$this->getBaseUrl() . '/oauth/authorize', $state
);
}
@@ -41,7 +54,7 @@ class Provider extends AbstractProvider implements ProviderInterface
*/
protected function getTokenUrl(): string
{
return 'https://id.anikeen.com/oauth/token';
return $this->getBaseUrl() . '/oauth/token';
}
/**
@@ -52,7 +65,7 @@ class Provider extends AbstractProvider implements ProviderInterface
protected function getUserByToken($token)
{
$response = $this->getHttpClient()->get(
'https://id.anikeen.com/api/v1/user', [
$this->getBaseUrl() . '/api/v1/user', [
'headers' => [
'Accept' => 'application/json',
'Authorization' => 'Bearer ' . $token,