From e42905c77df485ec6dcca11907ca750e068c0edd Mon Sep 17 00:00:00 2001 From: Alexander Strizhak Date: Thu, 29 Aug 2024 11:07:18 +0300 Subject: [PATCH] beautify phpDoc code examples (#496) --- .github/workflows/ci-mssql.yml | 8 +- .github/workflows/main.yml | 2 +- src/Collection/ArrayCollectionFactory.php | 24 +-- src/Parser/AbstractNode.php | 22 +-- src/Select.php | 174 ++++++++++------------ src/Select/JoinableLoader.php | 3 +- tests/docker-compose.yml | 2 +- 7 files changed, 113 insertions(+), 122 deletions(-) diff --git a/.github/workflows/ci-mssql.yml b/.github/workflows/ci-mssql.yml index 281855aa..462e1304 100644 --- a/.github/workflows/ci-mssql.yml +++ b/.github/workflows/ci-mssql.yml @@ -24,16 +24,16 @@ jobs: mssql: 'server:2017-latest' - php: '8.0' extensions: pdo, pdo_sqlsrv - mssql: 'server:2019-latest' + mssql: 'server:2019-CU25-ubuntu-20.04' - php: '8.1' extensions: pdo, pdo_sqlsrv - mssql: 'server:2019-latest' + mssql: 'server:2019-CU25-ubuntu-20.04' - php: '8.2' extensions: pdo, pdo_sqlsrv - mssql: 'server:2019-latest' + mssql: 'server:2019-CU25-ubuntu-20.04' - php: '8.3' extensions: pdo, pdo_sqlsrv - mssql: 'server:2019-latest' + mssql: 'server:2019-CU25-ubuntu-20.04' services: mssql: diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 2b21ad92..5ed5e346 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -28,7 +28,7 @@ jobs: - name: Setup DB services run: | cd tests - docker-compose up -d + docker compose up -d cd .. - name: Setup PHP ${{ matrix.php-version }} uses: shivammathur/setup-php@v2 diff --git a/src/Collection/ArrayCollectionFactory.php b/src/Collection/ArrayCollectionFactory.php index a67f3d65..0233689a 100644 --- a/src/Collection/ArrayCollectionFactory.php +++ b/src/Collection/ArrayCollectionFactory.php @@ -11,23 +11,23 @@ * In the case of a relation loaded lazily in a proxy mapper, * you should note that writing to such array collection should take place after an overloading: * - * + * // {$user->posts} is not loaded * - * // {$user->posts} is not loaded + * // Bad code: + * // Exception or notice will be thrown + * // because the {$user->posts} value comes from a __get method. + * $user->posts[] = new Post; * - * // Bad code: - * $user->posts[] = new Post; // Exception or notice will be thrown - * // because the {$user->posts} value comes from a __get method. * - * // Bad code: - * $posts = &$user->posts; // Exception or notice will be thrown - * // because the {$user->posts} value comes from a __get method. + * // Bad code: + * // Exception or notice will be thrown + * // because the {$user->posts} value comes from a __get method. + * $posts = &$user->posts; * - * // Correct example: - * $user->post; // Resolve relation. It can be any `reading` code - * $user->post[] = new Post; // * - * + * // Correct example: + * $user->post; // Resolve relation. It can be any `reading` code + * $user->post[] = new Post; * * @template TCollection of array * diff --git a/src/Parser/AbstractNode.php b/src/Parser/AbstractNode.php index fc95446a..3af539f2 100644 --- a/src/Parser/AbstractNode.php +++ b/src/Parser/AbstractNode.php @@ -265,11 +265,12 @@ public function mergeInheritanceNodes(bool $includeRole = false): void * (inner key) and reference criteria (outer key value). * * Example (default ORM Loaders): - * $this->parent->mount('profile', 'id', 1, [ - * 'id' => 100, - * 'user_id' => 1, - * ... - * ]); + * + * $this->parent->mount('profile', 'id', 1, [ + * 'id' => 100, + * 'user_id' => 1, + * // ... + * ]); * * In this example "id" argument is inner key of "user" record and it's linked to outer key * "user_id" in "profile" record, which defines reference criteria as 1. @@ -308,11 +309,12 @@ protected function mount(string $container, string $index, array $criteria, arra * (inner key) and reference criteria (outer key value). * * Example (default ORM Loaders): - * $this->parent->mountArray('comments', 'id', 1, [ - * 'id' => 100, - * 'user_id' => 1, - * ... - * ]); + * + * $this->parent->mountArray('comments', 'id', 1, [ + * 'id' => 100, + * 'user_id' => 1, + * // ... + * ]); * * In this example "id" argument is inner key of "user" record and it's linked to outer key * "user_id" in "profile" record, which defines reference criteria as 1. diff --git a/src/Select.php b/src/Select.php index fc23339b..04c5adb4 100644 --- a/src/Select.php +++ b/src/Select.php @@ -223,36 +223,34 @@ public function offset(int $offset): self * * Examples: * - * // Select users and load their comments (will cast 2 queries, HAS_MANY comments) - * User::find()->with('comments'); + * // Select users and load their comments (will cast 2 queries, HAS_MANY comments) + * User::find()->with('comments'); * - * // You can load chain of relations - select user and load their comments and post related to - * //comment - * User::find()->with('comments.post'); + * // You can load chain of relations - select user and load their comments and post related to comment + * User::find()->with('comments.post'); * - * // We can also specify custom where conditions on data loading, let's load only public - * // comments. - * User::find()->load('comments', [ - * 'where' => ['{@}.status' => 'public'] - * ]); + * // We can also specify custom where conditions on data loading, let's load only public comments. + * User::find()->load('comments', [ + * 'where' => ['{@}.status' => 'public'] + * ]); * * Please note using "{@}" column name, this placeholder is required to prevent collisions and * it will be automatically replaced with valid table alias of pre-loaded comments table. * - * // In case where your loaded relation is MANY_TO_MANY you can also specify pivot table - * // conditions, let's pre-load all approved user tags, we can use same placeholder for pivot - * // table alias - * User::find()->load('tags', [ - * 'wherePivot' => ['{@}.approved' => true] - * ]); - * - * // In most of cases you don't need to worry about how data was loaded, using external query - * // or left join, however if you want to change such behaviour you can force load method - * // using {@see Select::SINGLE_QUERY} - * User::find()->load('tags', [ - * 'method' => Select::SINGLE_QUERY, - * 'wherePivot' => ['{@}.approved' => true] - * ]); + * // In case where your loaded relation is MANY_TO_MANY you can also specify pivot table + * // conditions, let's pre-load all approved user tags, we can use same placeholder for pivot + * // table alias + * User::find()->load('tags', [ + * 'wherePivot' => ['{@}.approved' => true] + * ]); + * + * // In most of cases you don't need to worry about how data was loaded, using external query + * // or left join, however if you want to change such behaviour you can force load method + * // using {@see Select::SINGLE_QUERY} + * User::find()->load('tags', [ + * 'method' => Select::SINGLE_QUERY, + * 'wherePivot' => ['{@}.approved' => true] + * ]); * * Attention, you will not be able to correctly paginate in this case and only ORM loaders * support different loading types. @@ -260,7 +258,8 @@ public function offset(int $offset): self * You can specify multiple loaders using array as first argument. * * Example: - * User::find()->load(['posts', 'comments', 'profile']); + * + * User::find()->load(['posts', 'comments', 'profile']); * * Attention, consider disabling entity map if you want to use recursive loading (i.e * post.tags.posts), but first think why you even need recursive relation loading. @@ -306,90 +305,79 @@ public function load(string|array $relation, array $options = []): self * * Examples: * - * Find all users who have comments comments - * ```php - * User::find()->with('comments'); - * ``` - * - * Find all users who have approved comments (we can use comments table alias in where statement) - * ```php - * User::find()->with('comments')->where('comments.approved', true); - * ``` - * - * Find all users who have posts which have approved comments - * ```php - * User::find()->with('posts.comments')->where('posts_comments.approved', true); - * ``` - * - * Custom join alias for post comments relation - * ```php - * $user->with('posts.comments', [ - * 'as' => 'comments' - * ])->where('comments.approved', true); - * ``` - * - * If you joining MANY_TO_MANY relation you will be able to use pivot table used as relation - * name plus "_pivot" postfix. Let's load all users with approved tags. - * ```php - * $user->with('tags')->where('tags_pivot.approved', true); - * ``` - * - * You can also use custom alias for pivot table as well - * ```php - * User::find()->with('tags', [ - * 'pivotAlias' => 'tags_connection' - * ]) - * ->where('tags_connection.approved', false); - * ``` + * // Find all users who have comments comments + * User::find()->with('comments'); + * + * // Find all users who have approved comments (we can use comments table alias in where statement) + * User::find()->with('comments')->where('comments.approved', true); + * + * // Find all users who have posts which have approved comments + * User::find()->with('posts.comments')->where('posts_comments.approved', true); + * + * // Custom join alias for post comments relation + * $user->with('posts.comments', [ + * 'as' => 'comments' + * ])->where('comments.approved', true); + * + * // If you joining MANY_TO_MANY relation you will be able to use pivot table used as relation name plus "_pivot" postfix. Let's load all users with approved tags. + * $user->with('tags')->where('tags_pivot.approved', true); + * + * // You can also use custom alias for pivot table as well + * User::find()->with('tags', [ + * 'pivotAlias' => 'tags_connection' + * ]) + * ->where('tags_connection.approved', false); + * * * You can safely combine with() and load() methods. * - * Load all users with approved comments and pre-load all their comments - * ```php - * User::find()->with('comments')->where('comments.approved', true)->load('comments'); - * ``` + * // Load all users with approved comments and pre-load all their comments + * User::find() + * ->with('comments') + * ->where('comments.approved', true)->load('comments'); * * You can also use custom conditions in this case, let's find all users with approved * comments and pre-load such approved comments - * ```php - * User::find()->with('comments') + * + * User::find() + * ->with('comments') * ->where('comments.approved', true) * ->load('comments', [ - * 'where' => ['{@}.approved' => true] - * ]); - * ``` + * 'where' => ['{@}.approved' => true] + * ]); * * As you might notice previous construction will create 2 queries, however we can simplify * this construction to use already joined table as source of data for relation via "using" keyword - * ```php - * User::find()->with('comments') - * ->where('comments.approved', true) - * ->load('comments', ['using' => 'comments']); - * ``` + * + * User::find() + * ->with('comments') + * ->where('comments.approved', true) + * ->load('comments', ['using' => 'comments']); * * You will get only one query with INNER JOIN, to better understand this example let's use * custom alias for comments in with() method. - * ```php - * User::find()->with('comments', ['as' => 'commentsR']) - * ->where('commentsR.approved', true) - * ->load('comments', ['using' => 'commentsR']); - * ``` + * + * User::find() + * ->with('comments', ['as' => 'commentsR']) + * ->where('commentsR.approved', true) + * ->load('comments', ['using' => 'commentsR']); * * To use with() twice on the same relation, you can use `alias` option. - * ```php - * Country::find() - * // Find all translations - * ->with('translations', [ 'as' => 'trans']) - * ->load('translations', ['using' => 'trans']) - * // Second `with` for sorting only - * ->with('translations', [ - * 'as' => 'transEn', // Alias for SQL - * 'alias' => 'translations-en', // Alias for ORM to not to overwrite previous `with` - * 'method' => JoinableLoader::LEFT_JOIN, - * 'where' => ['locale' => 'en'], - * ]) - * ->orderBy('transEn.title', 'ASC'); - * ``` + * + * Country::find() + * // Find all translations + * ->with('translations', [ 'as' => 'trans']) + * ->load('translations', ['using' => 'trans']) + * // Second `with` for sorting only + * ->with('translations', [ + * // Alias for SQL + * 'as' => 'transEn', + * // Alias for ORM to not to overwrite previous `with` + * 'alias' => 'translations-en', + * 'method' => JoinableLoader::LEFT_JOIN, + * 'where' => ['locale' => 'en'], + * ]) + * ->orderBy('transEn.title', 'ASC'); * * @return static * diff --git a/src/Select/JoinableLoader.php b/src/Select/JoinableLoader.php index cb070dc3..60c77c46 100644 --- a/src/Select/JoinableLoader.php +++ b/src/Select/JoinableLoader.php @@ -277,7 +277,8 @@ protected function calculateAlias(AbstractLoader $parent): string * fetched from schema. * * Example: - * $this->getKey(Relation::OUTER_KEY); + * + * $this->getKey(Relation::OUTER_KEY); */ protected function localKey(string|int $key): ?string { diff --git a/tests/docker-compose.yml b/tests/docker-compose.yml index a0ca57a3..444b5be5 100644 --- a/tests/docker-compose.yml +++ b/tests/docker-compose.yml @@ -2,7 +2,7 @@ version: "3" services: cycle-sqlserver: - image: mcr.microsoft.com/mssql/server:2019-latest + image: mcr.microsoft.com/mssql/server:2019-CU25-ubuntu-20.04 ports: - "11433:1433" environment: