fix: docs

Author: binaryk

UPGRADING.md

@@ -1,5 +1,173 @@
 # Upgrading
 
+## From 9.x to 10.x
+
+### New Features
+
+#### Modern Model Definition with PHP Attributes
+
+Laravel Restify v10 introduces a modern way to define models using PHP 8+ attributes. While your existing static property approach will continue to work, we recommend migrating to the new attribute-based syntax for better developer experience.
+
+**Before (v9 and earlier):**
+```php
+class UserRepository extends Repository
+{
+    public static string $model = User::class;
+    
+    public function fields(RestifyRequest $request): array
+    {
+        return [
+            field('name'),
+            field('email'),
+        ];
+    }
+}
+```
+
+**After (v10 - Recommended):**
+```php
+use Binaryk\LaravelRestify\Attributes\Model;
+
+#[Model(User::class)]
+class UserRepository extends Repository
+{
+    public function fields(RestifyRequest $request): array
+    {
+        return [
+            field('name'),
+            field('email'),
+        ];
+    }
+}
+```
+
+**Benefits of migrating to attributes:**
+- 🎯 **Modern, declarative approach** - More intuitive and cleaner code
+- 🔍 **Better IDE support** - Enhanced autocompletion and static analysis
+- 📦 **Type-safe** - Use `::class` syntax for better refactoring support
+- 🔧 **More discoverable** - Attributes are easier to find with reflection tools
+- 🚀 **Future-proof** - Follows modern PHP practices
+
+**Migration Strategy:**
+
+1. **No immediate action required** - All existing repositories continue to work as-is
+2. **Gradual migration** - Update repositories one at a time when convenient
+3. **Mixed approach** - You can use both attributes and static properties in the same codebase
+
+**Priority order for model resolution:**
+1. `#[Model]` attribute (highest priority)
+2. `public static string $model` property
+3. Auto-guessing from repository class name (lowest priority)
+
+This change is **100% backward compatible** - no existing code will break.
+
+#### Improved Field-Level Search and Sorting
+
+Laravel Restify v10 introduces a more intuitive way to define searchable and sortable fields directly on the field definitions. While the static array approach continues to work, the new field-level methods provide better organization and discoverability.
+
+**Before (v9 and earlier):**
+```php
+class UserRepository extends Repository
+{
+    public static array $search = ['name', 'email'];
+    public static array $sort = ['name', 'email', 'created_at'];
+    
+    public function fields(RestifyRequest $request): array
+    {
+        return [
+            field('name'),
+            field('email'),
+            field('created_at'),
+        ];
+    }
+}
+```
+
+**After (v10 - Recommended):**
+```php
+#[Model(User::class)]
+class UserRepository extends Repository
+{
+    public function fields(RestifyRequest $request): array
+    {
+        return [
+            field('name')->searchable()->sortable(),
+            field('email')->searchable()->sortable(),
+            field('created_at')->sortable(),
+        ];
+    }
+}
+```
+
+**Benefits of field-level configuration:**
+- 📍 **Co-located configuration** - Search/sort behavior defined alongside the field
+- 🔍 **Better discoverability** - Easy to see which fields are searchable/sortable at a glance  
+- 🎛️ **More granular control** - Configure search and sort behavior per field
+- 🧹 **Cleaner repositories** - Reduces static array properties
+- 💡 **IDE-friendly** - Better autocompletion and method chaining
+
+**Migration Strategy:**
+
+1. **Static arrays still work** - No need to change existing repositories immediately
+2. **Field-level takes precedence** - If both are defined, field-level configuration wins
+3. **Gradual migration** - Update fields one at a time or per repository
+4. **Mixed approach** - You can use both approaches in the same codebase during transition
+
+**Priority order for search/sort resolution:**
+1. Field-level `->searchable()`/`->sortable()` methods (highest priority)
+2. Static `$search`/`$sort` arrays (fallback)
+
+This change is also **100% backward compatible** - existing static arrays continue to work perfectly.
+
+### Configuration File Updates
+
+When upgrading to v10, it's important to ensure your local `config/restify.php` file includes all the new configuration options that have been added.
+
+**Recommended Steps:**
+
+1. **Compare configuration files** - Check your local `config/restify.php` against the latest version
+2. **Review new sections** - Look for new configuration options that may have been added
+3. **Merge changes** - Add any missing configuration sections to your local file
+
+**New configuration sections in v10 may include:**
+
+```php
+// Example new sections (check the actual config file for current options)
+'mcp' => [
+    'tools' => [
+        'exclude' => [],
+        'include' => [],
+    ],
+    'resources' => [
+        'exclude' => [],
+        'include' => [],
+    ],
+    'prompts' => [
+        'exclude' => [],
+        'include' => [],
+    ],
+],
+
+'ai_solutions' => [
+    'model' => 'gpt-4.1-mini',
+    'max_tokens' => 1000,
+],
+```
+
+**How to update your config:**
+
+1. **Backup your current config** - Copy your existing `config/restify.php`
+2. **Republish the config** (optional):
+   ```bash
+   php artisan vendor:publish --provider="Binaryk\LaravelRestify\LaravelRestifyServiceProvider" --tag="config" --force
+   ```
+3. **Merge your custom settings** - Copy your custom values back into the new config file
+4. **Test your application** - Ensure all functionality works as expected
+
+<alert type="warning">
+Always backup your existing configuration before making changes, especially if you have custom settings.
+</alert>
+
 ## From 7.3.1 to 7.4.0
 
 ## Breaking

docs-v2/content/en/api/repositories.md

@@ -23,7 +23,26 @@ instruct Restify to generate the migrations, policy, and model (in `app/Models`)
 
 ## Defining Repositories
 
-The basic repository form looks like this:
+The basic repository form looks like this using the modern attribute approach:
+
+```php
+namespace App\Restify;
+
+use App\Models\Post;
+use App\Restify\Repository;
+use Binaryk\LaravelRestify\Attributes\Model;
+
+#[Model(Post::class)]
+class PostRepository extends Repository
+{
+    public function fields(RestifyRequest $request): array
+    {
+        return [];
+    }
+}
+```
+
+Or using the traditional static property approach:
 
 ```php
 namespace App\Restify;
@@ -35,15 +54,15 @@ class PostRepository extends Repository
 {
     public static string $model = Post::class;
 
-    public function fields(RestifyRequest $request)
+    public function fields(RestifyRequest $request): array
     {
         return [];
     }
 }
 ```
 
 <alert type="info">
-If you don't specify the $model property, Restify will try to guess the model automatically.
+If you don't specify the model using an attribute or the $model property, Restify will try to guess the model automatically based on the repository class name.
 </alert>
 
 
@@ -54,8 +73,12 @@ The `fields` method returns the default set of attributes definitions that shoul
 Restify will discover recursively all classes from the `app\Restify\*` directory that extend
 the `Binaryk\LaravelRestify\Repositories\Repository` class.
 
-If the `$model` property is not defined, Restify will guess the model class by using the prefix of the Repository name.
-For example, `UserPostRepository` class has the model `UserPost`.
+For model resolution, Restify follows this priority order:
+1. **`#[Model]` attribute** (highest priority)
+2. **`$model` static property**  
+3. **Auto-guessing** from repository class name (lowest priority)
+
+When auto-guessing, Restify uses the prefix of the Repository name. For example, `UserPostRepository` class will try to find the `UserPost` model.
 
 ### Actions handled by the Repository
 
@@ -90,16 +113,77 @@ for full model update, and respectively partial update.
 
 </alert>
 
-## Model name
+## Model Definition
 
 As we already noticed, each repository basically works as a wrapper over a specific resource. The fancy
 naming `resource` is nothing more than a database entity (posts, users etc.). To make the repository aware of the
-entity it should handle, we need to define the model property associated with this resource:
+entity it should handle, we need to define the model associated with this resource.
+
+Laravel Restify provides three ways to define the model, with the following priority order:
+
+### 1. Modern Approach: PHP Attributes (Recommended)
+
+The most modern and clean approach uses PHP 8+ attributes:
+
+```php
+use Binaryk\LaravelRestify\Attributes\Model;
+
+#[Model(Post::class)]
+class PostRepository extends Repository
+{
+    // Clean - no static property needed
+    public function fields(RestifyRequest $request): array
+    {
+        return [
+            field('title'),
+            field('content'),
+        ];
+    }
+}
+```
+
+You can also use string class names:
+
+```php
+#[Model('App\Models\Post')]
+class PostRepository extends Repository
+{
+    // Fields...
+}
+```
+
+**Benefits of using attributes:**
+- Modern, declarative approach
+- Better IDE support and static analysis
+- Cleaner code (no need for static properties)
+- More discoverable with reflection tools
+- Type-safe when using `::class` syntax
+
+### 2. Traditional Approach: Static Property
+
+The classic approach using static properties (still fully supported):
 
 ```php
-public static string $model = 'App\\Models\\Post'; 
+class PostRepository extends Repository
+{
+    public static string $model = Post::class;
+    
+    // Or with string
+    public static string $model = 'App\\Models\\Post';
+}
 ```
 
+### 3. Auto-Guessing (Fallback)
+
+If neither attribute nor static property is defined, Restify will automatically guess the model from the repository class name:
+
+- `UserRepository` → tries `App\Models\User`
+- `BlogPostRepository` → tries `App\Models\BlogPost`
+
+<alert type="info">
+The attribute approach takes the highest priority, followed by the static property, and finally auto-guessing as a fallback.
+</alert>
+
 ## Public repository
 
 Sometimes, you might find yourself facing the risk of exposing public information (allowing unauthenticated users to access it).

src/Attributes/Model.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Binaryk\LaravelRestify\Attributes;
+
+use Attribute;
+use InvalidArgumentException;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+class Model
+{
+    public readonly string $modelClass;
+
+    public function __construct(string $modelClass)
+    {
+        if (empty($modelClass)) {
+            throw new InvalidArgumentException('Model class cannot be empty');
+        }
+
+        $this->modelClass = $modelClass;
+    }
+
+    public function getModelClass(): string
+    {
+        return $this->modelClass;
+    }
+}

src/Fields/BelongsTo.php

@@ -51,17 +51,19 @@ public function searchable(...$attributes): self
         if (count($attributes) === 1 && is_array($attributes[0])) {
             $this->searchablesAttributes = collect($attributes[0])->flatten()->all();
             // Also call parent with the first attribute for consistency
-            if (!empty($this->searchablesAttributes)) {
+            if (! empty($this->searchablesAttributes)) {
                 parent::searchable($this->searchablesAttributes[0]);
             }
+
             return $this;
         }
 
         // If it's relationship-specific multiple attributes (all strings), use BelongsTo behavior
-        if (count($attributes) > 1 && collect($attributes)->every(fn($attr) => is_string($attr))) {
+        if (count($attributes) > 1 && collect($attributes)->every(fn ($attr) => is_string($attr))) {
             $this->searchablesAttributes = collect($attributes)->flatten()->all();
             // Also call parent to maintain consistency with CanSearch trait
             parent::searchable($attributes[0]);
+
             return $this;
         }
 
@@ -98,7 +100,7 @@ public function getSearchables(): array
     public function getSearchColumn(?RestifyRequest $request = null): mixed
     {
         // If we have BelongsTo-specific attributes, return the first one for compatibility
-        if (!empty($this->searchablesAttributes)) {
+        if (! empty($this->searchablesAttributes)) {
             return $this->searchablesAttributes[0];
         }
 

src/Fields/Concerns/CanSearch.php

@@ -59,8 +59,8 @@ public function searchable(...$attributes): self
         if (is_string($firstAttribute)) {
             $this->searchableColumn = $firstAttribute;
             // Check if second parameter is a type
-            $this->searchableType = (count($attributes) > 1 && is_string($attributes[1])) 
-                ? $attributes[1] 
+            $this->searchableType = (count($attributes) > 1 && is_string($attributes[1]))
+                ? $attributes[1]
                 : 'text';
 
             return $this;