docs: adds Laravel-specific doc parts

Author: vinceAmstoutz

core/subresources.md

@@ -5,17 +5,23 @@ In API Platform you can declare as many `ApiResource` as you want on a PHP class
 creating Subresources.
 
 Subresources work well by implementing your own state [providers](./state-providers.md)
-or [processors](./state-processors.md). In API Platform we provide a working Doctrine layer for
-subresources providing you add the correct configuration for URI Variables.
+or [processors](./state-processors.md). In API Platform, we provide functional Doctrine and Eloquent layers for 
+subresources, as long as the correct configuration for URI variables is added.
 
 ## URI Variables Configuration
 
-URI Variables are configured via the `uriVariables` node on an `ApiResource`. It's an array indexed by the variables present in your URI, `/companies/{companyId}/employees/{id}` has two uri variables `companyId` and `id`. For each of these, we need to create a `Link` between the previous and the next node, in this example the link between a Company and an Employee.
+URI Variables are configured via the `uriVariables` node on an `ApiResource`. It's an array indexed by the variables
+present in your URI, `/companies/{companyId}/employees/{id}` has two uri variables `companyId` and `id`.
+For each of these, we need to create a `Link` between the previous and the next node, in this example the link between a
+Company and an Employee.
 
-If you're using the Doctrine implementation, queries are automatically built using the provided links.
+If you're using the Doctrine or the Eloquent implementation, queries are automatically built using the provided links.
 
 ### Answer to a Question
 
+> [!NOTE]
+> In Symfony we use the term “entities”, while the following documentation is mostly for Laravel “models”.
+
 For this example we have two classes, a Question and an Answer. We want to find the Answer to
 the Question about the Universe using the following URI: `/question/42/answer`.
 
@@ -82,6 +88,7 @@ class Question
 ```
 
 ```yaml
+# The YAML syntax is only supported for Symfony
 # api/config/api_platform/resources.yaml
 resources:
     App\Entity\Answer: ~
@@ -90,6 +97,7 @@ resources:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8" ?>
+<!--The XML syntax is only supported for Symfony-->
 <!-- api/config/api_platform/resources.xml -->
 
 <resources xmlns="https://api-platform.com/schema/metadata/resources-3.0"
@@ -138,6 +146,7 @@ class Answer
 ```
 
 ```yaml
+# The YAML syntax is only supported for Symfony
 # api/config/api_platform/resources.yaml
 resources:
     App\Entity\Answer:
@@ -153,6 +162,7 @@ resources:
 ```
 
 ```xml
+<!--The XML syntax is only supported for Symfony-->
 <resources xmlns="https://api-platform.com/schema/metadata/resources-3.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
@@ -197,6 +207,7 @@ If we had a `relatedQuestions` property on the `Answer` we could retrieve the co
 ```
 
 ```yaml
+#The YAML syntax is only supported for Symfony
 # api/config/api_platform/resources.yaml
 resources:
     App\Entity\Question:
@@ -210,6 +221,7 @@ resources:
 ```
 
 ```xml
+<!--The XML syntax is only supported for Symfony-->
 <resource class="App\Entity\Question" uriTemplate="/answers/{id}/related_questions.{_format}">
     <uriVariables>
         <uriVariable parameterName="id" fromClass="App\Entity\Answer" fromProperty="relatedQuestions"/>
@@ -226,6 +238,9 @@ resources:
 
 ### Company Employee's
 
+> [!NOTE]
+> In Symfony we use the term “entities”, while the following documentation is mostly for Laravel “models”.
+
 Note that in this example, we declared an association using Doctrine only between Employee and Company using a ManyToOne. There is no inverse association hence the use of `toProperty` in the URI Variables definition.
 
 The following declares a few subresources:
@@ -253,7 +268,8 @@ use Doctrine\ORM\Mapping as ORM;
     uriVariables: [
         'companyId' => new Link(fromClass: Company::class, toProperty: 'company'),
         'id' => new Link(fromClass: Employee::class),
-    ],
+    ],In Laravel 
+
     operations: [ new Get() ]
 )]
 #[ApiResource(
@@ -310,7 +326,7 @@ class Company
 }
 ```
 
-We did not define any Doctrine annotation here and if we want things to work properly with GraphQL, we need to map the `employees` field as a Link to the class `Employee` using the property `company`.
+We did not define any Doctrine or Eloquent annotation here and if we want things to work properly with GraphQL, we need to map the `employees` field as a Link to the class `Employee` using the property `company`.
 
 As a general rule, if the property we want to create a link from is in the `fromClass`, use `fromProperty`, if not, use `toProperty`.
 
@@ -335,12 +351,15 @@ class Company {
 
 ## Security
 
-In order to use Symfony's built-in security system on subresources the security option of the `Link` attribute can be used.
+In order to use Symfony's or the Laravel built-in security system on subresources the security option of the `Link` attribute can be used.
+
+### Symfony example for security
 
 To restrict the access to a subresource based on the parent object simply use the Symfony expression language as you would do normally, with the exception that the name defined in `toProperty` or `fromProperty` is used to access the object.
 
 Alternatively you can also use the `securityObjectName` to set a custom name.
 
+
 ```php
 <?php 
 #[ApiResource(
@@ -358,10 +377,44 @@ class Company {
 }
 ```
 
+### Laravel example for security
+
+With Laravel, we can use the following code:
+
+```php
+<?php 
+#[ApiResource(
+    uriTemplate: '/employees/{employeeId}/company',
+    uriVariables: [
+        'employeeId' => new Link(fromClass: Employee::class, toProperty: 'company', security: Gate::allows('some_voter', $company)),
+    ],
+    operations: [
+        new Get()
+    ]
+)]
+
+class Company {
+    // ...
+}
+```
+
 This is currently an experimental feature disabled by default. To enable it please set `enable_link_security` to true:
 
+### Symfony configuration to disable link security
+
 ```yaml
 # api/config/packages/api_platform.yaml
 api_platform:
     enable_link_security: true
 ```
+
+### Laravel configuration to disable link security
+
+```php
+<?php
+// config/api-platform.php
+return [
+    // ....
+    'enable_link_security' => true,
+];
+```