From e0ed638a13e49ab44356153cb7e2510b2f7f604e Mon Sep 17 00:00:00 2001
From: Mateusz Charytoniuk <mateusz.charytoniuk@protonmail.com>
Date: Thu, 14 Dec 2023 00:14:40 +0100
Subject: [PATCH] chore: oauth2 docs
---
config.ini.example | 1 +
.../{server => }/authorization-code-grant.md | 4 +-
.../oauth2/{server => }/configuration.md | 0
.../security/oauth2/enabling-grants.md | 89 +++++++++++++++++++
.../oauth2/{server => }/installation.md | 0
.../enabling-grants.md => persistent-data.md} | 86 +-----------------
src/Command/StaticPagesBuild.php | 2 +-
src/DatabaseConnectionPoolConfiguration.php | 2 +-
.../DatabaseConfigurationProvider.php | 2 +-
9 files changed, 100 insertions(+), 86 deletions(-)
rename docs/pages/docs/features/security/oauth2/{server => }/authorization-code-grant.md (96%)
rename docs/pages/docs/features/security/oauth2/{server => }/configuration.md (100%)
create mode 100644 docs/pages/docs/features/security/oauth2/enabling-grants.md
rename docs/pages/docs/features/security/oauth2/{server => }/installation.md (100%)
rename docs/pages/docs/features/security/oauth2/{server/enabling-grants.md => persistent-data.md} (73%)
diff --git a/config.ini.example b/config.ini.example
index 27877231..2494f641 100644
--- a/config.ini.example
+++ b/config.ini.example
@@ -2,6 +2,7 @@
env = development
esbuild_metafile = esbuild-meta-app.json
scheme = https
+url = https://resonance.distantmagic.com
[database]
default[driver] = mysql
diff --git a/docs/pages/docs/features/security/oauth2/server/authorization-code-grant.md b/docs/pages/docs/features/security/oauth2/authorization-code-grant.md
similarity index 96%
rename from docs/pages/docs/features/security/oauth2/server/authorization-code-grant.md
rename to docs/pages/docs/features/security/oauth2/authorization-code-grant.md
index d1e8d84a..f35543bf 100644
--- a/docs/pages/docs/features/security/oauth2/server/authorization-code-grant.md
+++ b/docs/pages/docs/features/security/oauth2/authorization-code-grant.md
@@ -1,7 +1,9 @@
---
collections:
- - documents
+ - name: documents
+ next: docs/features/security/oauth2/persistent-data
layout: dm:document
+next: docs/features/security/oauth2/persistent-data
parent: docs/features/security/oauth2/index
title: Authorization Code Grant
description: >
diff --git a/docs/pages/docs/features/security/oauth2/server/configuration.md b/docs/pages/docs/features/security/oauth2/configuration.md
similarity index 100%
rename from docs/pages/docs/features/security/oauth2/server/configuration.md
rename to docs/pages/docs/features/security/oauth2/configuration.md
diff --git a/docs/pages/docs/features/security/oauth2/enabling-grants.md b/docs/pages/docs/features/security/oauth2/enabling-grants.md
new file mode 100644
index 00000000..ceeaf29f
--- /dev/null
+++ b/docs/pages/docs/features/security/oauth2/enabling-grants.md
@@ -0,0 +1,89 @@
+---
+collections:
+ - name: documents
+ next: docs/features/security/oauth2/authorization-code-grant
+layout: dm:document
+next: docs/features/security/oauth2/authorization-code-grant
+parent: docs/features/security/oauth2/index
+title: Enabling Grants
+description: >
+ Learn how to add methods of acquiring access tokens.
+---
+
+# Enabling Grants
+
+Grant represents a method of obtaining an access token or, in other words,
+different authentication flows (through password, token, etc.).
+
+By default, the OAuth2 server has no grants enabled, so you have to add at
+least one if you want to use it.
+
+# Usage
+
+You can follow
+[thephpleague/oauth2-server](https://oauth2.thephpleague.com/authorization-server/which-grant/)
+recommendations to decide which grants you want to enable. You can either use
+League's built-in grants or provide your own.
+
+## Doctrine Considerations
+
+If you want to implement repositories by using
+{{docs/features/database/doctrine/index}}, you should probably use
+`withRepository()` method to obtain the Entity Manager. For example:
+
+```php
+<?php
+
+use Distantmagic\Resonance\DoctrineEntityManagerRepository;
+use Doctrine\ORM\EntityRepository;
+
+#[Singleton(provides: AccessTokenRepositoryInterface::class)]
+readonly class OAuth2AccessTokenRepository implements AccessTokenRepositoryInterface
+{
+ public function __construct(private DoctrineEntityManagerRepository $doctrineEntityManagerRepository)
+ {
+ }
+
+ public function getNewToken(ClientEntityInterface $clientEntity, array $scopes, $userIdentifier = null)
+ {
+ $this
+ ->doctrineEntityManagerRepository
+ ->withRepository(MyDoctrineTokenRepository::class, function (EntityRepository $entityRepository) {
+ // ...
+ })
+ ;
+
+ // ...
+ }
+
+ // ...
+}
+```
+
+## Enabling Grant Types
+
+For each grant you want to enable you have to add a grant provider. For
+example, if you want to enable client credentials grant:
+
+```php file:app/OAuth2GrantProvider/ClientCredentialsGrantProvider.php
+<?php
+
+namespace App\OAuth2GrantProvider;
+
+use Distantmagic\Resonance\Attribute\ProvidesOAuth2Grant;
+use Distantmagic\Resonance\Attribute\Singleton;
+use Distantmagic\Resonance\OAuth2GrantProvider;
+use Distantmagic\Resonance\SingletonCollection;
+use League\OAuth2\Server\Grant\ClientCredentialsGrant;
+use League\OAuth2\Server\Grant\GrantTypeInterface;
+
+#[ProvidesOAuth2Grant]
+#[Singleton(collection: SingletonCollection::OAuth2Grant)]
+readonly class ClientCredentialsGrantProvider extends OAuth2GrantProvider
+{
+ public function getGrant(): GrantTypeInterface
+ {
+ return new ClientCredentialsGrant();
+ }
+}
+```
diff --git a/docs/pages/docs/features/security/oauth2/server/installation.md b/docs/pages/docs/features/security/oauth2/installation.md
similarity index 100%
rename from docs/pages/docs/features/security/oauth2/server/installation.md
rename to docs/pages/docs/features/security/oauth2/installation.md
diff --git a/docs/pages/docs/features/security/oauth2/server/enabling-grants.md b/docs/pages/docs/features/security/oauth2/persistent-data.md
similarity index 73%
rename from docs/pages/docs/features/security/oauth2/server/enabling-grants.md
rename to docs/pages/docs/features/security/oauth2/persistent-data.md
index e589a6c4..a9e92802 100644
--- a/docs/pages/docs/features/security/oauth2/server/enabling-grants.md
+++ b/docs/pages/docs/features/security/oauth2/persistent-data.md
@@ -1,22 +1,14 @@
---
collections:
- - name: documents
- next: docs/features/security/oauth2/authorization-code-grant
+ - documents
layout: dm:document
-next: docs/features/security/oauth2/authorization-code-grant
parent: docs/features/security/oauth2/index
-title: Enabling Grants
+title: Persistent Data
description: >
- Learn how to add methods of acquiring access tokens.
+ Learn how to persist OAuth2 tokens and other data by using Doctrine.
---
-# Enabling Grants
-
-Grant represents a method of obtaining an access token or, in other words,
-different authentication flows (through password, token, etc.).
-
-By default, the OAuth2 server has no grants enabled, so you have to add at
-least one if you want to use it.
+# Persistent Data
You can implement only the ones you need in your application. Grants use
repositories to store and retrieve the data they need to operate.
@@ -33,76 +25,6 @@ additional step compared to other grant types (exchanging code for an access
token instead of immediately generating access token), thus it has it's own
documentation page that explains the process further.
-# Doctrine Considerations
-
-If you want to implement repositories by using
-{{docs/features/database/doctrine/index}}, you should probably use
-`withRepository()` method to obtain the Entity Manager. For example:
-
-```php
-<?php
-
-use Distantmagic\Resonance\DoctrineEntityManagerRepository;
-use Doctrine\ORM\EntityRepository;
-
-#[Singleton(provides: AccessTokenRepositoryInterface::class)]
-readonly class OAuth2AccessTokenRepository implements AccessTokenRepositoryInterface
-{
- public function __construct(private DoctrineEntityManagerRepository $doctrineEntityManagerRepository)
- {
- }
-
- public function getNewToken(ClientEntityInterface $clientEntity, array $scopes, $userIdentifier = null)
- {
- $this
- ->doctrineEntityManagerRepository
- ->withRepository(MyDoctrineTokenRepository::class, function (EntityRepository $entityRepository) {
- // ...
- })
- ;
-
- // ...
- }
-
- // ...
-}
-```
-
-# Usage
-
-You can follow
-[thephpleague/oauth2-server](https://oauth2.thephpleague.com/authorization-server/which-grant/)
-recommendations to decide which grants you want to enable. You can either use
-League's built-in grants or provide your own.
-
-## Enabling Grant Types
-
-For each grant you want to enable you have to add a grant provider. For
-example, if you want to enable client credentials grant:
-
-```php file:app/OAuth2GrantProvider/ClientCredentialsGrantProvider.php
-<?php
-
-namespace App\OAuth2GrantProvider;
-
-use Distantmagic\Resonance\Attribute\ProvidesOAuth2Grant;
-use Distantmagic\Resonance\Attribute\Singleton;
-use Distantmagic\Resonance\OAuth2GrantProvider;
-use Distantmagic\Resonance\SingletonCollection;
-use League\OAuth2\Server\Grant\ClientCredentialsGrant;
-use League\OAuth2\Server\Grant\GrantTypeInterface;
-
-#[ProvidesOAuth2Grant]
-#[Singleton(collection: SingletonCollection::OAuth2Grant)]
-readonly class ClientCredentialsGrantProvider extends OAuth2GrantProvider
-{
- public function getGrant(): GrantTypeInterface
- {
- return new ClientCredentialsGrant();
- }
-}
-```
-
## Persistent Data Repositories
You can learn more on {{docs/features/database/doctrine/entity-managers}} page.
diff --git a/src/Command/StaticPagesBuild.php b/src/Command/StaticPagesBuild.php
index d6a5b22d..efaffa28 100644
--- a/src/Command/StaticPagesBuild.php
+++ b/src/Command/StaticPagesBuild.php
@@ -24,7 +24,7 @@ final class StaticPagesBuild extends CoroutineCommand
protected function executeInCoroutine(InputInterface $input, OutputInterface $output): int
{
- $this->staticPageProcessor->process(...);
+ $this->staticPageProcessor->process();
return Command::SUCCESS;
}
diff --git a/src/DatabaseConnectionPoolConfiguration.php b/src/DatabaseConnectionPoolConfiguration.php
index 6564d40c..4eed44a0 100644
--- a/src/DatabaseConnectionPoolConfiguration.php
+++ b/src/DatabaseConnectionPoolConfiguration.php
@@ -26,7 +26,7 @@ readonly class DatabaseConnectionPoolConfiguration
#[SensitiveParameter]
public int $port,
#[SensitiveParameter]
- public string $unixSocket,
+ public ?string $unixSocket,
#[SensitiveParameter]
public string $username,
) {}
diff --git a/src/SingletonProvider/ConfigurationProvider/DatabaseConfigurationProvider.php b/src/SingletonProvider/ConfigurationProvider/DatabaseConfigurationProvider.php
index 2cf098b5..abbed870 100644
--- a/src/SingletonProvider/ConfigurationProvider/DatabaseConfigurationProvider.php
+++ b/src/SingletonProvider/ConfigurationProvider/DatabaseConfigurationProvider.php
@@ -50,7 +50,7 @@ final readonly class DatabaseConfigurationProvider extends ConfigurationProvider
'pool_prefill' => Expect::bool()->required(),
'pool_size' => Expect::int()->min(1)->required(),
'port' => Expect::int()->min(1)->max(65535)->default(3306),
- 'unix_socket' => Expect::string()->min(1)->nullable()->default(null),
+ 'unix_socket' => Expect::string()->nullable()->default(null),
'username' => Expect::string()->min(1)->required(),
]);
--
GitLab