BaseService

Core service class providing query building, CRUD operations, caching, and export functionality

Overview

BaseService is the heart of the package’s query processing engine. It provides:

• Advanced query building: Dynamic filters, relations, pagination, ordering
• CRUD operations: Create, read, update, delete with validation
• Caching layer: Configurable caching with versioning and invalidation
• Hierarchy support: Tree-structured data retrieval
• Export functionality: Excel and PDF generation
• Relation filtering: Nested queries with whereHas

Create a service for each model by extending BaseService and passing the model class to the constructor.

Constructor

public function __construct(Model|string $modelClass)

modelClass · Model|string · required

The Eloquent model class (instance or class name string)

Example:

use App\Models\User;
use Ronu\RestGenericClass\Core\Services\BaseService;

class UserService extends BaseService
{
    public function __construct()
    {
        parent::__construct(User::class);
    }
}

Query Methods

list_all()

public function list_all($params, $toJson = true): mixed

Retrieves all records matching query parameters.

params · array · required

Query parameters object with the following optional keys:

• relations: Array or JSON string of relations to eager load
• select: Fields to select (array or comma-separated string)
• attr / eq: Equality filters (deprecated, use oper instead)
• oper: Advanced filter conditions (see Filter Syntax)
• orderby: Array of ['field' => 'asc'|'desc']
• pagination: Pagination config (see Pagination)
• hierarchy: Hierarchy mode config (see Hierarchy)
• _nested: If true, applies relation filters to eager loading

toJson · bool · default: "true"

Return JSON-serializable array (vs raw collection)

return · array|LengthAwarePaginator|CursorPaginator

Results depend on pagination:

• No pagination: ['data' => [...]]
• With pagination: LengthAwarePaginator or CursorPaginator
• Hierarchy mode: Nested tree structure

Example:

$params = [
    'relations' => ['posts', 'roles'],
    'select' => ['id', 'name', 'email'],
    'oper' => [
        'and' => [
            'status = active',
            'created_at > 2024-01-01'
        ]
    ],
    'orderby' => [['created_at' => 'desc']],
    'pagination' => ['page' => 1, 'pageSize' => 20]
];

$result = $service->list_all($params);

get_one()

public function get_one($params, $toJson = true): mixed

Retrieves first record matching query parameters.

params · array · required

Same parameters as list_all() (pagination ignored)

toJson · bool · default: "true"

Return JSON-serializable array

return · array

['data' => Model|null]

Example:

$result = $service->get_one([
    'oper' => ['email = [e-mail]']
]);
// ['data' => ['id' => 1, 'name' => 'John', ...]]

show()

public function show($params, $id): mixed

Retrieves a single record by ID with optional relations.

params · array · required

• relations: Relations to load
• select: Fields to select
• hierarchy: Hierarchy mode (see showHierarchy())

id · mixed · required

Primary key value

return · Model|array

Model instance or hierarchical array structure

Example:

$user = $service->show(['relations' => ['posts', 'roles']], 1);

CRUD Methods

create()

public function create(array $params): array

Creates one or more records.

params · array · required

Single record attributes OR wrapped array:

// Single record
['name' => 'John', 'email' => '[e-mail]']

// Multiple records
['user' => [
    ['name' => 'John', 'email' => '[e-mail]'],
    ['name' => 'Jane', 'email' => '[e-mail]']
]]

return · array

[
  'success' => true,
  'model' => array // Created attributes
]
// OR for multiple:
[
  'success' => true,
  'models' => [
    ['success' => true, 'model' => [...]],
    ['success' => true, 'model' => [...]]
  ]
]

Example:

$result = $service->create([
    'name' => 'John Doe',
    'email' => '[e-mail]',
    'password' => bcrypt('secret')
]);

if ($result['success']) {
    $user = $result['model'];
}

update()

public function update(array $attributes, $id, $validate = false): array

Updates a single record by ID.

attributes · array · required

Fields to update (partial updates supported)

id · mixed · required

Primary key or fieldKeyUpdate value

validate · bool · default: "false"

Run validation before saving

return · array

[
  'success' => true,
  'model' => array // Updated attributes
]
// OR on validation failure:
[
  'success' => false,
  'errors' => [...]
]

Example:

$result = $service->update(
    ['status' => 'active', 'verified_at' => now()],
    1,
    true // validate
);

update_multiple()

public function update_multiple(array $params, $validate = false): array

Updates multiple records at once.

params · array · required

Array of records with primary keys:

[
  ['id' => 1, 'status' => 'active'],
  ['id' => 2, 'status' => 'inactive']
]

validate · bool · default: "false"

Validate each record before saving

return · array

[
  'success' => true,
  'models' => [
    ['success' => true, 'model' => [...]],
    ['success' => false, 'errors' => [...]]
  ]
]

destroy()

public function destroy($id): array

Deletes a record by ID.

id · mixed · required

Primary key value

return · array

['success' => true, 'model' => Model]

Example:

$result = $service->destroy(1);
if ($result['success']) {
    // Record deleted
}

destroybyid()

public function destroybyid($id): array

Deletes records using Eloquent’s static destroy() method (supports multiple IDs).

id · mixed|array · required

Single ID or array of IDs

Example:

// Delete multiple
$result = $service->destroybyid([1, 2, 3]);

Hierarchy Methods

showHierarchy()

public function showHierarchy(array $params, mixed $id): array

Retrieves a record in hierarchical structure.

params · array · required

Query params with hierarchy config:

[
  'hierarchy' => [
    'mode' => 'with_descendants', // or 'node_only', 'with_ancestors', 'full_branch'
    'children_key' => 'children',
    'max_depth' => null, // or integer
    'include_empty_children' => true
  ],
  'relations' => [...],
  'select' => [...]
]

id · mixed · required

Record ID

return · array

Nested tree structure based on mode:

• node_only: Just the node with empty children array
• with_descendants: Node + all descendants as nested tree
• with_ancestors: Chain from root down to node
• full_branch: Entire branch (ancestors + node + descendants)

Example:

$category = $service->showHierarchy([
    'hierarchy' => [
        'mode' => 'with_descendants',
        'max_depth' => 2
    ],
    'relations' => ['products']
], 5);

// Returns nested structure:
// [
//   'id' => 5,
//   'name' => 'Electronics',
//   'children' => [
//     ['id' => 10, 'name' => 'Phones', 'children' => [...]],
//     ['id' => 11, 'name' => 'Laptops', 'children' => [...]]
//   ]
// ]

Export Methods

exportExcel()

public function exportExcel($params)

Exports query results to Excel file.

params · array · required

Same query params as list_all() plus:

• filename: Output filename (default: excel.xlsx)
• columns: Columns to include (default: uses select or all fillable)

return · BinaryFileResponse

Excel file download response

Example:

return $service->exportExcel([
    'oper' => ['status = active'],
    'columns' => ['id', 'name', 'email', 'created_at'],
    'filename' => 'active-users.xlsx'
]);

exportPdf()

public function exportPdf($params)

Exports query results to PDF file.

params · array · required

Same query params plus:

• filename: Output filename (default: pdf_file.pdf)
• template: Blade view name (default: pdf)
• columns: Columns to include

return · Response

PDF file download response

Example:

return $service->exportPdf([
    'oper' => ['created_at >= 2024-01-01'],
    'template' => 'reports.users',
    'filename' => 'users-report.pdf'
]);

Filter Syntax (oper)

The oper parameter supports advanced filtering with logical operators and conditions.

Structure

[
    'and' => [
        'field operator value',
        'another_field operator value'
    ],
    'or' => [
        'status = active',
        'status = pending'
    ]
]

Supported Operators

• =, !=, <, >, <=, >=
• like, not like, ilike, not ilike
• in, not in
• between, not between
• date, not date
• null, not null
• exists, not exists
• regexp, not regexp

Examples

// Simple AND conditions
$params = [
    'oper' => [
        'status = active',
        'created_at > 2024-01-01'
    ]
];

// Mixed AND/OR
$params = [
    'oper' => [
        'and' => [
            'status = active',
            'verified = 1'
        ],
        'or' => [
            'role = admin',
            'role = moderator'
        ]
    ]
];

// Relation filters (requires model to have RELATIONS defined)
$params = [
    'oper' => [
        'posts' => [
            'published = 1',
            'created_at > 2024-01-01'
        ]
    ],
    'relations' => ['posts']
];

// With _nested=true, filters apply to eager loaded data
$params = [
    'oper' => [
        'posts' => ['published = 1']
    ],
    'relations' => ['posts'],
    '_nested' => true
];

Pagination

Standard Pagination

$params = [
    'pagination' => [
        'page' => 1,
        'pageSize' => 20
    ]
];

$result = $service->list_all($params);
// Returns Laravel LengthAwarePaginator

Cursor Pagination (Infinite Scroll)

$params = [
    'pagination' => [
        'pageSize' => 20,
        'infinity' => true,
        'cursor' => null // or cursor from previous response
    ]
];

$result = $service->list_all($params);
// Returns Laravel CursorPaginator

Caching

BaseService includes a built-in caching layer with versioning.

Configuration

In config/rest-generic-class.php:

'cache' => [
    'enabled' => true,
    'store' => 'redis', // or null for default
    'ttl' => 3600, // seconds
    'ttl_by_method' => [
        'list_all' => 1800,
        'get_one' => 3600,
    ],
    'cacheable_methods' => ['list_all', 'get_one'],
    'vary' => [
        'headers' => ['Accept-Language', 'X-Tenant-ID']
    ]
],

Cache Invalidation

Cache is automatically invalidated (version bumped) after:

• create()
• update()
• update_multiple()
• destroy()
• destroybyid()

Per-Request Control

// Disable cache for this request
$params = ['cache' => false];

// Custom TTL for this request
$params = ['cache_ttl' => 600]; // 10 minutes

$result = $service->list_all($params);

Relations with Field Selection

Load relations with specific fields to optimize queries.

$params = [
    'relations' => [
        'posts:id,title,published_at',
        'roles:id,name',
        'comments'
    ]
];

$result = $service->list_all($params);

Important: Foreign keys are automatically included even if not specified.

Nested Relations

$params = [
    'relations' => [
        'posts',
        'posts.comments',
        'posts.comments.author'
    ]
];

Complete Example

use App\Models\User;
use Ronu\RestGenericClass\Core\Services\BaseService;

class UserService extends BaseService
{
    public function __construct()
    {
        parent::__construct(User::class);
    }
    
    public function getActiveUsersWithPosts()
    {
        return $this->list_all([
            'relations' => ['posts:id,title,created_at', 'roles'],
            'select' => ['id', 'name', 'email', 'created_at'],
            'oper' => [
                'and' => [
                    'status = active',
                    'email_verified_at != null'
                ],
                'posts' => ['published = 1']
            ],
            'orderby' => [['created_at' => 'desc']],
            'pagination' => ['page' => 1, 'pageSize' => 20],
            '_nested' => true
        ]);
    }
}

// Usage in controller
$service = new UserService();
$result = $service->getActiveUsersWithPosts();

Related

BaseModel

Model class with validation and hierarchy support

RestController

Controller exposing service methods as REST endpoints

Filter Syntax

Complete guide to filter operators and syntax