Merge pull request 'new-api' (#4) from new-api into clean-main

Reviewed-on: #4

app/Http/Controllers/api/BylawApiController.php

@@ -13,9 +13,6 @@ class BylawApiController extends Controller
 {
     use BaseApiResponse;
 
-    /**
-     * Get all Bylaw Subject Categories
-     */
     public function categories()
     {
         $categories = BylawSubjectCategory::all()->map(function ($category) {
@@ -28,9 +25,6 @@ class BylawApiController extends Controller
         return $this->success($categories, 'Success', 'Bylaw Categories List');
     }
 
-    /**
-     * Get all Bylaw Legal Authorities
-     */
     public function authorities()
     {
         $authorities = BylawLegalAuthority::all()->map(function ($authority) {
@@ -44,15 +38,13 @@ class BylawApiController extends Controller
         return $this->success($authorities, 'Success', 'Bylaw Authorities List');
     }
 
-    /**
-     * Get Paginated Bylaws (Filtered & Sorted by Approval Date)
-     */
     public function index(Request $request)
     {
         $request->validate([
             'category_id'           => 'nullable|exists:bylaw_subject_categories,id',
             'approval_authority_id' => 'nullable|exists:bylaw_legal_authorities,id',
             'bylaw_type'            => 'nullable|in:executive,delegated,independent',
+            'sort_by'               => 'nullable|in:date,number',
             'sort'                  => 'nullable|in:asc,desc',
             'per_page'              => 'nullable|integer|min:1|max:100',
         ]);
@@ -72,8 +64,15 @@ class BylawApiController extends Controller
             $query->where('bylaw_type', $request->bylaw_type);
         }
 
+        $sortBy = $request->input('sort_by', 'date');
         $sortOrder = $request->input('sort', 'desc');
-        $query->orderBy('approval_date', $sortOrder);
+        $sortColumn = $sortBy === 'number' ? 'promulgation_number' : 'approval_date';
+
+        if ($sortBy === 'number') {
+            $query->orderByRaw("LENGTH({$sortColumn}) {$sortOrder}")->orderBy($sortColumn, $sortOrder);
+        } else {
+            $query->orderBy($sortColumn, $sortOrder);
+        }
 
         $perPage = min(max((int) $request->input('per_page', 15), 10), 100);
         $paginator = $query->paginate($perPage);
@@ -93,13 +92,12 @@ class BylawApiController extends Controller
         return $this->success($responseData, 'Success', 'Bylaws Fetched');
     }
 
-    /**
-     * Search Bylaws by Keyword
-     */
     public function search(Request $request)
     {
         $request->validate([
             'search'   => 'nullable|string',
+            'sort_by'  => 'nullable|in:date,number',
+            'sort'     => 'nullable|in:asc,desc',
             'per_page' => 'nullable|integer|min:1|max:100',
         ]);
 
@@ -117,10 +115,18 @@ class BylawApiController extends Controller
             });
         }
 
-        $perPage = min(max((int) $request->input('per_page', 15), 10), 100);
+        $sortBy = $request->input('sort_by', 'date');
+        $sortOrder = $request->input('sort', 'desc');
+        $sortColumn = $sortBy === 'number' ? 'promulgation_number' : 'approval_date';
 
-        // Default search sort to newest first
+        if ($sortBy === 'number') {
-        $paginator = $query->orderBy('approval_date', 'desc')->paginate($perPage);
+            $query->orderByRaw("LENGTH({$sortColumn}) {$sortOrder}")->orderBy($sortColumn, $sortOrder);
+        } else {
+            $query->orderBy($sortColumn, $sortOrder);
+        }
+
+        $perPage = min(max((int) $request->input('per_page', 15), 10), 100);
+        $paginator = $query->paginate($perPage);
 
         $items = collect($paginator->items())->map(function ($item) {
             return $this->formatBylaw($item);
@@ -137,9 +143,33 @@ class BylawApiController extends Controller
         return $this->success($responseData, 'Success', 'Search Results Fetched');
     }
 
-    /**
+    public function fast_search(Request $request)
-     * Contextual Pager API
+    {
-     */
+        $searchTerm = $request->input('search');
+
+        $query = BylawDocument::with(['category', 'approvalAuthority', 'promulgationAuthority'])
+            ->where('is_published', true);
+
+        if (!empty($searchTerm)) {
+            $query->where(function ($q) use ($searchTerm) {
+                $q->where('title', 'LIKE', "%{$searchTerm}%")
+                    ->orWhere('description', 'LIKE', "%{$searchTerm}%")
+                    ->orWhere('promulgation_number', 'LIKE', "%{$searchTerm}%")
+                    ->orWhere('official_gazette_number', 'LIKE', "%{$searchTerm}%");
+            });
+        }
+
+        $count = $query->count();
+        $items = $query->orderBy('approval_date', 'desc')->take(5)->get()->map(function ($item) {
+            return $this->formatBylaw($item);
+        });
+
+        return $this->success([
+            'items' => $items,
+            'count' => $count
+        ], 'Success', 'Fast Search Results');
+    }
+
     public function pager($id)
     {
         $current = BylawDocument::with(['category', 'approvalAuthority', 'promulgationAuthority'])
@@ -199,11 +229,15 @@ class BylawApiController extends Controller
         return $this->success($results, 'Success', 'Pager Window Details');
     }
 
-    /**
+    private function isLockedForCurrentUser($item): bool
-     * Helper to uniformly format the Bylaw Document payload
+    {
-     */
+        return ! auth()->user()->isSubscriber() && (bool) ($item->is_locked ?? false);
+    }
+
     private function formatBylaw($item)
     {
+        $isLocked = $this->isLockedForCurrentUser($item);
+
         return [
             'id'                        => $item->id,
             'title'                     => $item->title,
@@ -219,8 +253,9 @@ class BylawApiController extends Controller
             'execution_date'            => $item->execution_date,
             'bylaw_type'                => $item->bylaw_type,
             'global_status'             => $item->global_status,
-            'pdf_file_url'              => $item->pdf_file_path ? asset('storage/' . $item->pdf_file_path) : null,
+            'pdf_file_url'              => $isLocked ? null : ($item->pdf_file_path ? asset('storage/' . $item->pdf_file_path) : null),
-            'description'               => $item->description,
+            'description'               => $isLocked ? null : $item->description,
+            'is_locked'                 => $isLocked,
         ];
     }
 }

app/Http/Controllers/api/GlobalSearchApiController.php

@@ -25,12 +25,14 @@ class GlobalSearchApiController extends Controller
     use BaseApiResponse;
 
     /**
-     * Massive Search across ALL data types
+     * Massive Search across ALL data types (With dynamic Date/Number Sorting)
      */
     public function search(Request $request)
     {
         $request->validate([
             'search'   => 'nullable|string',
+            'sort_by'  => 'nullable|in:date,number',
+            'sort'     => 'nullable|in:asc,desc',
             'per_page' => 'nullable|integer|min:1|max:100',
             'page'     => 'nullable|integer|min:1',
         ]);
@@ -86,11 +88,22 @@ class GlobalSearchApiController extends Controller
                 });
             $results = $results->merge($opinions);
 
-            // 4. Search Laws, Arts, and Structural Models
+            // 4. Search Arts
+            $arts = Art::with(['law.category'])
+                ->where('title', 'LIKE', "%{$searchTerm}%")
+                ->orWhere('text', 'LIKE', "%{$searchTerm}%")
+                ->take($limitPerTable)->get()->map(function($item) use ($searchTerm) {
+                    $formatted = $this->formatArt($item, $searchTerm, Art::class);
+                    $formatted['type'] = 'art';
+                    return $formatted;
+                });
+            $results = $results->merge($arts);
+
+            // 5. Search Laws and Structural Models
             $structuralModels = [
                 Law::class, Volum::class, Book::class, Division::class,
                 Section::class, Chapter::class, Part::class, Gate::class,
-                Branch::class, Art::class,
+                Branch::class
             ];
 
             foreach ($structuralModels as $modelClass) {
@@ -98,22 +111,11 @@ class GlobalSearchApiController extends Controller
                 $modelInstance = new $modelClass;
                 $table = $modelInstance->getTable();
 
-                if ($table === 'art') {
+                $query->where('title', 'LIKE', "%{$searchTerm}%");
-                    $query->where('title', 'LIKE', "%{$searchTerm}%")
-                        ->orWhere('text', 'LIKE', "%{$searchTerm}%");
-                } else {
-                    $query->where('title', 'LIKE', "%{$searchTerm}%");
-                }
 
-                $items = $query->take($limitPerTable)->get()->map(function($item) use ($modelClass, $table, $searchTerm) {
+                $items = $query->take($limitPerTable)->get()->map(function($item) use ($modelClass, $table) {
-                    if ($table === 'art') {
+                    $formatted = $this->formatStructure($item, $modelClass);
-                        $formatted = $this->formatArt($item, $searchTerm, $modelClass);
+                    $formatted['type'] = ($table === 'section') ? 'sections' : $table;
-                        $formatted['type'] = 'art';
-                    } else {
-                        $formatted = $this->formatStructure($item, $modelClass);
-                        // Standardize the structural type names (laws, sections, etc.)
-                        $formatted['type'] = ($table === 'section') ? 'sections' : $table;
-                    }
                     return $formatted;
                 });
 
@@ -121,12 +123,41 @@ class GlobalSearchApiController extends Controller
             }
         }
 
-        // --- Execute Manual Pagination on the Combined Collection ---
+        // --- Apply Dynamic Memory Sorting ---
+        if ($request->has('sort_by')) {
+            $sortBy = $request->input('sort_by');
+            $sortOrder = $request->input('sort', 'desc');
+
+            if ($sortBy === 'number') {
+                $sortCallback = function ($item) {
+                    // Extract whatever number property this specific item uses
+                    return (string) ($item['promulgation_number'] ?? $item['ruling_number'] ?? $item['opinion_number'] ?? $item['number'] ?? '');
+                };
+
+                // Use Natural Sorting so "2" comes before "10"
+                if ($sortOrder === 'asc') {
+                    $results = $results->sortBy($sortCallback, SORT_NATURAL)->values();
+                } else {
+                    $results = $results->sortByDesc($sortCallback, SORT_NATURAL)->values();
+                }
+            } elseif ($sortBy === 'date') {
+                $sortCallback = function ($item) {
+                    // Extract whatever date property this specific item uses (Note: Structural models will default to '' and group together)
+                    return (string) ($item['approval_date'] ?? $item['ruling_date'] ?? $item['opinion_date'] ?? '');
+                };
+
+                if ($sortOrder === 'asc') {
+                    $results = $results->sortBy($sortCallback)->values();
+                } else {
+                    $results = $results->sortByDesc($sortCallback)->values();
+                }
+            }
+        }
+
+        // --- Execute Manual Pagination on the Sorted Collection ---
         $total = $results->count();
-        // Slice the array for the exact page requested
         $paginatedItems = $results->forPage($page, $perPage)->values();
 
-        // Build a proper Laravel paginator object so the response metadata remains identical
         $paginator = new LengthAwarePaginator(
             $paginatedItems,
             $total,
@@ -146,12 +177,126 @@ class GlobalSearchApiController extends Controller
         return $this->success($responseData, 'Success', 'Global Search Results Fetched');
     }
 
+    /**
+     * Top-level fast search for quick dropdown UI elements
+     */
+    public function fast_search(Request $request)
+    {
+        $searchTerm = $request->input('search');
+        $results = collect();
+        $totalCount = 0;
+
+        // Take a max of 3 from each table so the quick-search array doesn't become too heavy
+        $limitPerTable = 3;
+
+        if (!empty($searchTerm)) {
+
+            // 1. Bylaw Documents
+            $bylawQuery = BylawDocument::with(['category', 'approvalAuthority', 'promulgationAuthority'])
+                ->where('is_published', true)
+                ->where(function ($q) use ($searchTerm) {
+                    $q->where('title', 'LIKE', "%{$searchTerm}%")
+                        ->orWhere('description', 'LIKE', "%{$searchTerm}%")
+                        ->orWhere('promulgation_number', 'LIKE', "%{$searchTerm}%")
+                        ->orWhere('official_gazette_number', 'LIKE', "%{$searchTerm}%");
+                });
+            $totalCount += $bylawQuery->count();
+            $bylaws = $bylawQuery->take($limitPerTable)->get()->map(function($item) {
+                $formatted = $this->formatBylaw($item);
+                $formatted['type'] = 'bylaw';
+                return $formatted;
+            });
+            $results = $results->merge($bylaws);
+
+            // 2. Judicial Precedents
+            $judicialQuery = JudicialPrecedent::with('category')
+                ->where(function ($q) use ($searchTerm) {
+                    $q->where('ruling_number', 'LIKE', "%{$searchTerm}%")
+                        ->orWhere('subject', 'LIKE', "%{$searchTerm}%")
+                        ->orWhere('full_text', 'LIKE', "%{$searchTerm}%");
+                });
+            $totalCount += $judicialQuery->count();
+            $judicials = $judicialQuery->take($limitPerTable)->get()->map(function($item) {
+                $formatted = $this->formatJudicial($item);
+                $formatted['type'] = 'judicial_precedent';
+                return $formatted;
+            });
+            $results = $results->merge($judicials);
+
+            // 3. Legal Opinions
+            $opinionQuery = LegalOpinion::with('category')
+                ->where(function ($q) use ($searchTerm) {
+                    $q->where('opinion_number', 'LIKE', "%{$searchTerm}%")
+                        ->orWhere('subject', 'LIKE', "%{$searchTerm}%")
+                        ->orWhere('full_text', 'LIKE', "%{$searchTerm}%")
+                        ->orWhere('issuing_authority', 'LIKE', "%{$searchTerm}%");
+                });
+            $totalCount += $opinionQuery->count();
+            $opinions = $opinionQuery->take($limitPerTable)->get()->map(function($item) {
+                $formatted = $this->formatOpinion($item);
+                $formatted['type'] = 'legal_opinion';
+                return $formatted;
+            });
+            $results = $results->merge($opinions);
+
+            // 4. Search Arts
+            $artQuery = Art::with(['law.category'])
+                ->where('title', 'LIKE', "%{$searchTerm}%")
+                ->orWhere('text', 'LIKE', "%{$searchTerm}%");
+            $totalCount += $artQuery->count();
+            $arts = $artQuery->take($limitPerTable)->get()->map(function($item) use ($searchTerm) {
+                $formatted = $this->formatArt($item, $searchTerm, Art::class);
+                $formatted['type'] = 'art';
+                return $formatted;
+            });
+            $results = $results->merge($arts);
+
+            // 5. Structural Models
+            $structuralModels = [
+                Law::class, Volum::class, Book::class, Division::class,
+                Section::class, Chapter::class, Part::class, Gate::class,
+                Branch::class
+            ];
+
+            foreach ($structuralModels as $modelClass) {
+                $query = $modelClass::query();
+                $modelInstance = new $modelClass;
+                $table = $modelInstance->getTable();
+
+                $query->where('title', 'LIKE', "%{$searchTerm}%");
+
+                $totalCount += $query->count();
+
+                if ($results->count() < 15) {
+                    $items = $query->take($limitPerTable)->get()->map(function($item) use ($modelClass, $table) {
+                        $formatted = $this->formatStructure($item, $modelClass);
+                        $formatted['type'] = ($table === 'section') ? 'sections' : $table;
+                        return $formatted;
+                    });
+                    $results = $results->merge($items);
+                }
+            }
+        }
+
+        return $this->success([
+            'items' => $results->take(15)->values(),
+            'count' => $totalCount
+        ], 'Success', 'Global Fast Search Results');
+    }
+
     /* -----------------------------------------------------------------
      * FORMATTING HELPERS
      * ----------------------------------------------------------------- */
 
+    private function isLockedForCurrentUserGeneric($item): bool
+    {
+        return ! auth()->user()->isSubscriber() && (bool) ($item->is_locked ?? false);
+    }
+
     private function formatBylaw($item)
     {
+        $isLocked = $this->isLockedForCurrentUserGeneric($item);
+
         return [
             'id'                        => $item->id,
             'title'                     => $item->title,
@@ -159,42 +304,48 @@ class GlobalSearchApiController extends Controller
             'approval_authority_name'   => optional($item->approvalAuthority)->name,
             'approval_date'             => $item->approval_date,
             'promulgation_number'       => $item->promulgation_number,
-            'description'               => $item->description,
+            'description'               => $isLocked ? null : $item->description,
+            'is_locked'                 => $isLocked,
         ];
     }
 
     private function formatJudicial($item)
     {
+        $isLocked = $this->isLockedForCurrentUserGeneric($item);
+
         return [
             'id'                => $item->id,
-            'title'             => $item->subject, // Map subject to title for universal UI parsing
+            'title'             => $item->subject,
             'ruling_number'     => $item->ruling_number,
             'ruling_date'       => $item->ruling_date,
-            'text'              => $item->full_text,
+            'text'              => $isLocked ? null : $item->full_text,
             'issuing_authority' => $item->issuing_authority,
             'category_name'     => optional($item->category)->name,
+            'is_locked'         => $isLocked,
         ];
     }
 
     private function formatOpinion($item)
     {
+        $isLocked = $this->isLockedForCurrentUserGeneric($item);
+
         return [
             'id'                => $item->id,
-            'title'             => $item->subject, // Map subject to title for universal UI parsing
+            'title'             => $item->subject,
             'opinion_number'    => $item->opinion_number,
             'opinion_date'      => $item->opinion_date,
-            'text'              => $item->full_text,
+            'text'              => $isLocked ? null : $item->full_text,
             'issuing_authority' => $item->issuing_authority,
             'category_name'     => optional($item->category)->name,
+            'is_locked'         => $isLocked,
         ];
     }
 
     private function formatArt($item, $searchTerm, $modelClass)
     {
-        $law = Law::find($item->law_id);
+        $law = $item->law ?? Law::find($item->law_id);
-        $isLocked = $this->isLockedForCurrentUser($law);
+        $isLocked = ! auth()->user()->isSubscriber() && (bool) $law?->is_locked;
 
-        // Text snippet highlighting logic (from ArtController)
         $text = $item->text ?? '';
         $searchQuoted = preg_quote($searchTerm, '/');
         if (!empty($text) && preg_match('/\b(.{0,50})\b('.$searchQuoted.')\b(.{0,50})\b/i', $text, $matches)) {
@@ -206,6 +357,7 @@ class GlobalSearchApiController extends Controller
         return [
             'id'          => $item->id,
             'title'       => $item->title,
+            'number'      => $item->number, // Added for sorting capability
             'text'        => $isLocked ? null : $context,
             'is_locked'   => $isLocked,
             'route'       => array_values($this->route($modelClass, $item)),
@@ -221,12 +373,12 @@ class GlobalSearchApiController extends Controller
     private function formatStructure($item, $modelClass)
     {
         $law = Law::find($item?->law_id ?? $item->id);
-        $isLocked = $this->isLockedForCurrentUser($law);
+        $isLocked = ! auth()->user()->isSubscriber() && (bool) $law?->is_locked;
 
         $payload = [
             'id'        => $item->id,
             'title'     => $item->title,
-            'number'    => $item->number,
+            'number'    => $item->number, // Available for sorting capability
             'is_locked' => $isLocked,
             'route'     => array_values($this->route($modelClass, $item)),
             'law'       => $law?->title ?? '',
@@ -240,15 +392,6 @@ class GlobalSearchApiController extends Controller
         return $payload;
     }
 
-    /* -----------------------------------------------------------------
-     * UTILITY METHODS
-     * ----------------------------------------------------------------- */
-
-    private function isLockedForCurrentUser(?Law $law): bool
-    {
-        return ! auth()->user()->isSubscriber() && (bool) $law?->is_locked;
-    }
-
     private function route($modelClass, $query)
     {
         if ((new $modelClass)->getTable() == 'art') {

app/Http/Controllers/api/JudicialPrecedentApiController.php

@@ -28,6 +28,7 @@ class JudicialPrecedentApiController extends Controller
     {
         $request->validate([
             'category_id' => 'nullable|exists:judicial_precedent_categories,id',
+            'sort_by'     => 'nullable|in:date,number',
             'sort'        => 'nullable|in:asc,desc',
             'per_page'    => 'nullable|integer|min:1|max:100',
         ]);
@@ -38,8 +39,16 @@ class JudicialPrecedentApiController extends Controller
             $query->where('category_id', $request->category_id);
         }
 
+        $sortBy = $request->input('sort_by', 'date');
         $sortOrder = $request->input('sort', 'desc');
-        $query->orderBy('ruling_date', $sortOrder);
+        $sortColumn = $sortBy === 'number' ? 'ruling_number' : 'ruling_date';
+
+        if ($sortBy === 'number') {
+            // Natural numeric sorting for string numbers
+            $query->orderByRaw("LENGTH({$sortColumn}) {$sortOrder}")->orderBy($sortColumn, $sortOrder);
+        } else {
+            $query->orderBy($sortColumn, $sortOrder);
+        }
 
         $perPage = min(max((int) $request->input('per_page', 15), 10), 100);
         $paginator = $query->paginate($perPage);
@@ -59,13 +68,12 @@ class JudicialPrecedentApiController extends Controller
         return $this->success($responseData, 'Success', 'Judicial Precedents Fetched');
     }
 
-    /**
-     * Search Judicial Precedents by Keyword
-     */
     public function search(Request $request)
     {
         $request->validate([
             'search'   => 'nullable|string',
+            'sort_by'  => 'nullable|in:date,number',
+            'sort'     => 'nullable|in:asc,desc',
             'per_page' => 'nullable|integer|min:1|max:100',
         ]);
 
@@ -81,8 +89,18 @@ class JudicialPrecedentApiController extends Controller
             });
         }
 
+        $sortBy = $request->input('sort_by', 'date');
+        $sortOrder = $request->input('sort', 'desc');
+        $sortColumn = $sortBy === 'number' ? 'ruling_number' : 'ruling_date';
+
+        if ($sortBy === 'number') {
+            $query->orderByRaw("LENGTH({$sortColumn}) {$sortOrder}")->orderBy($sortColumn, $sortOrder);
+        } else {
+            $query->orderBy($sortColumn, $sortOrder);
+        }
+
         $perPage = min(max((int) $request->input('per_page', 15), 10), 100);
-        $paginator = $query->orderBy('ruling_date', 'desc')->paginate($perPage);
+        $paginator = $query->paginate($perPage);
 
         $items = collect($paginator->items())->map(function ($item) {
             return $this->formatItem($item);
@@ -99,6 +117,30 @@ class JudicialPrecedentApiController extends Controller
         return $this->success($responseData, 'Success', 'Search Results Fetched');
     }
 
+    public function fast_search(Request $request)
+    {
+        $searchTerm = $request->input('search');
+        $query = JudicialPrecedent::query();
+
+        if (!empty($searchTerm)) {
+            $query->where(function ($q) use ($searchTerm) {
+                $q->where('ruling_number', 'LIKE', "%{$searchTerm}%")
+                    ->orWhere('subject', 'LIKE', "%{$searchTerm}%")
+                    ->orWhere('full_text', 'LIKE', "%{$searchTerm}%");
+            });
+        }
+
+        $count = $query->count();
+        $items = $query->orderBy('ruling_date', 'desc')->take(5)->get()->map(function ($item) {
+            return $this->formatItem($item);
+        });
+
+        return $this->success([
+            'items' => $items,
+            'count' => $count
+        ], 'Success', 'Fast Search Results');
+    }
+
     public function pager($id)
     {
         $current = JudicialPrecedent::find($id);
@@ -141,20 +183,25 @@ class JudicialPrecedentApiController extends Controller
         return $this->success($results, 'Success', 'Pager Window Details');
     }
 
-    /**
+    private function isLockedForCurrentUser($item): bool
-     * Helper method to format payload uniformly
+    {
-     */
+        return ! auth()->user()->isSubscriber() && (bool) ($item->is_locked ?? false);
+    }
+
     private function formatItem($item)
     {
+        $isLocked = $this->isLockedForCurrentUser($item);
+
         return [
             'id'                => $item->id,
             'ruling_number'     => $item->ruling_number,
             'ruling_date'       => $item->ruling_date,
             'subject'           => $item->subject,
-            'full_text'         => $item->full_text,
+            'full_text'         => $isLocked ? null : $item->full_text,
             'issuing_authority' => $item->issuing_authority,
             'category_id'       => $item->category_id,
             'category_name'     => optional($item->category)->name,
+            'is_locked'         => $isLocked,
         ];
     }
 }

app/Http/Controllers/api/LegalOpinionApiController.php

@@ -28,6 +28,7 @@ class LegalOpinionApiController extends Controller
     {
         $request->validate([
             'category_id' => 'nullable|exists:legal_opinion_categories,id',
+            'sort_by'     => 'nullable|in:date,number',
             'sort'        => 'nullable|in:asc,desc',
             'per_page'    => 'nullable|integer|min:1|max:100',
         ]);
@@ -38,8 +39,15 @@ class LegalOpinionApiController extends Controller
             $query->where('category_id', $request->category_id);
         }
 
+        $sortBy = $request->input('sort_by', 'date');
         $sortOrder = $request->input('sort', 'desc');
-        $query->orderBy('opinion_date', $sortOrder);
+        $sortColumn = $sortBy === 'number' ? 'opinion_number' : 'opinion_date';
+
+        if ($sortBy === 'number') {
+            $query->orderByRaw("LENGTH({$sortColumn}) {$sortOrder}")->orderBy($sortColumn, $sortOrder);
+        } else {
+            $query->orderBy($sortColumn, $sortOrder);
+        }
 
         $perPage = min(max((int) $request->input('per_page', 15), 10), 100);
         $paginator = $query->paginate($perPage);
@@ -59,13 +67,12 @@ class LegalOpinionApiController extends Controller
         return $this->success($responseData, 'Success', 'Legal Opinions Fetched');
     }
 
-    /**
-     * Search Legal Opinions by Keyword
-     */
     public function search(Request $request)
     {
         $request->validate([
             'search'   => 'nullable|string',
+            'sort_by'  => 'nullable|in:date,number',
+            'sort'     => 'nullable|in:asc,desc',
             'per_page' => 'nullable|integer|min:1|max:100',
         ]);
 
@@ -82,8 +89,18 @@ class LegalOpinionApiController extends Controller
             });
         }
 
+        $sortBy = $request->input('sort_by', 'date');
+        $sortOrder = $request->input('sort', 'desc');
+        $sortColumn = $sortBy === 'number' ? 'opinion_number' : 'opinion_date';
+
+        if ($sortBy === 'number') {
+            $query->orderByRaw("LENGTH({$sortColumn}) {$sortOrder}")->orderBy($sortColumn, $sortOrder);
+        } else {
+            $query->orderBy($sortColumn, $sortOrder);
+        }
+
         $perPage = min(max((int) $request->input('per_page', 15), 10), 100);
-        $paginator = $query->orderBy('opinion_date', 'desc')->paginate($perPage);
+        $paginator = $query->paginate($perPage);
 
         $items = collect($paginator->items())->map(function ($item) {
             return $this->formatItem($item);
@@ -100,6 +117,31 @@ class LegalOpinionApiController extends Controller
         return $this->success($responseData, 'Success', 'Search Results Fetched');
     }
 
+    public function fast_search(Request $request)
+    {
+        $searchTerm = $request->input('search');
+        $query = LegalOpinion::query();
+
+        if ($request->filled('search')) {
+            $query->where(function ($q) use ($searchTerm) {
+                $q->where('opinion_number', 'LIKE', "%{$searchTerm}%")
+                    ->orWhere('subject', 'LIKE', "%{$searchTerm}%")
+                    ->orWhere('full_text', 'LIKE', "%{$searchTerm}%")
+                    ->orWhere('issuing_authority', 'LIKE', "%{$searchTerm}%");
+            });
+        }
+
+        $count = $query->count();
+        $items = $query->orderBy('opinion_date', 'desc')->take(5)->get()->map(function ($item) {
+            return $this->formatItem($item);
+        });
+
+        return $this->success([
+            'items' => $items,
+            'count' => $count
+        ], 'Success', 'Fast Search Results');
+    }
+
     public function pager($id)
     {
         $current = LegalOpinion::find($id);
@@ -153,20 +195,25 @@ class LegalOpinionApiController extends Controller
         return $this->success($results, 'Success', 'Pager Window Details');
     }
 
-    /**
+    private function isLockedForCurrentUser($item): bool
-     * Helper method to format payload uniformly
+    {
-     */
+        return ! auth()->user()->isSubscriber() && (bool) ($item->is_locked ?? false);
+    }
+
     private function formatItem($item)
     {
+        $isLocked = $this->isLockedForCurrentUser($item);
+
         return [
             'id'                => $item->id,
             'opinion_number'    => $item->opinion_number,
             'opinion_date'      => $item->opinion_date,
             'subject'           => $item->subject,
-            'full_text'         => $item->full_text,
+            'full_text'         => $isLocked ? null : $item->full_text,
             'issuing_authority' => $item->issuing_authority,
             'category_id'       => $item->category_id,
             'category_name'     => optional($item->category)->name,
+            'is_locked'         => $isLocked,
         ];
     }
 }

routes/api.php

@@ -25,7 +25,6 @@ Route::prefix('v1')->group(function () {
     Route::post('verify', [AuthController::class, 'verify']);
     Route::post('version', [VersionController::class, 'index']);
     Route::post('/payment/callback', [SubscribePlanController::class, 'paymentCallback'])->name('payment.callback');
-
 });
 
 Route::prefix('v1')->middleware('auth:sanctum')->group(function () {
@@ -35,7 +34,7 @@ Route::prefix('v1')->middleware('auth:sanctum')->group(function () {
     Route::get('art', [ArtController::class, 'index']);
     Route::get('categories', [CategoriesController::class, 'index']);
     Route::post('art/search', [ArtController::class, 'search']);
-    Route::post('fast-search', [ArtController::class, 'fash_search']);
+    Route::post('fast-search', [ArtController::class, 'fash_search']); // Legacy Art fast search
     Route::post('art/note', [NoteController::class, 'create']);
     Route::put('art/note/{id}', [NoteController::class, 'update']);
     Route::delete('art/note/{id}', [NoteController::class, 'destroy']);
@@ -71,25 +70,29 @@ Route::prefix('v1')->middleware('auth:sanctum')->group(function () {
 
     Route::post('suggestions', [SuggestionController::class, 'index']);
 
-
+    // Judicial Precedents
     Route::get('judicial-precedents/categories', [\App\Http\Controllers\api\JudicialPrecedentApiController::class, 'categories']);
     Route::get('judicial-precedents', [\App\Http\Controllers\api\JudicialPrecedentApiController::class, 'index']);
     Route::get('judicial-precedents/{id}/pager', [\App\Http\Controllers\api\JudicialPrecedentApiController::class, 'pager']);
-    Route::post('judicial-precedents/search', [\App\Http\Controllers\api\JudicialPrecedentApiController::class, 'search']); // NEW
+    Route::post('judicial-precedents/search', [\App\Http\Controllers\api\JudicialPrecedentApiController::class, 'search']);
+    Route::post('judicial-precedents/fast-search', [\App\Http\Controllers\api\JudicialPrecedentApiController::class, 'fast_search']); // NEW
 
+    // Legal Opinions
     Route::get('legal-opinions/categories', [\App\Http\Controllers\api\LegalOpinionApiController::class, 'categories']);
     Route::get('legal-opinions', [\App\Http\Controllers\api\LegalOpinionApiController::class, 'index']);
     Route::get('legal-opinions/{id}/pager', [\App\Http\Controllers\api\LegalOpinionApiController::class, 'pager']);
-    Route::post('legal-opinions/search', [\App\Http\Controllers\api\LegalOpinionApiController::class, 'search']); // NEW
+    Route::post('legal-opinions/search', [\App\Http\Controllers\api\LegalOpinionApiController::class, 'search']);
+    Route::post('legal-opinions/fast-search', [\App\Http\Controllers\api\LegalOpinionApiController::class, 'fast_search']); // NEW
 
+    // Bylaws
     Route::get('bylaws/categories', [\App\Http\Controllers\api\BylawApiController::class, 'categories']);
     Route::get('bylaws/authorities', [\App\Http\Controllers\api\BylawApiController::class, 'authorities']);
     Route::get('bylaws', [\App\Http\Controllers\api\BylawApiController::class, 'index']);
     Route::get('bylaws/{id}/pager', [\App\Http\Controllers\api\BylawApiController::class, 'pager']);
     Route::post('bylaws/search', [\App\Http\Controllers\api\BylawApiController::class, 'search']);
+    Route::post('bylaws/fast-search', [\App\Http\Controllers\api\BylawApiController::class, 'fast_search']); // NEW
 
-
+    // Global Search
-
     Route::post('global-search', [\App\Http\Controllers\api\GlobalSearchApiController::class, 'search']);
-
+    Route::post('global-search/fast-search', [\App\Http\Controllers\api\GlobalSearchApiController::class, 'fast_search']); // NEW
 });