lexxsoft/odata

Laravel OData request parser

1.2.1 2024-09-01 11:54 UTC

Requires

• php: >=8.1
• ext-dom: *

Requires (Dev)

• laravel/framework: ^10.5

MIT

• Aleksey Komov

• library
• laravel
• odata
• universal platform

README

Contents

• Installation
  • Requirements
  • Setup
  • Update model requirements
• OData features
• Data manipulations
  • Reading data
  • Updating data
    • Updating relations
    • Updating relations with pivot
  • Creating data
  • Deleting data
• Using custom controller methods
• Data validation rules
• Spatie laravel permissions

Installation

Requirements

Component	Version
PHP	8.1
Laravel	10.5

Setup

composer require lexxsoft/odata

After installation all routes as /odata/* will be accessible

php artisan vendor:publish --provider="Lexxsoft\Odata\Providers\OdataServiceProvider"

After that config/odata.php file will appear.

Update model requirements

To make model as OData entity, you must use Restable trait.

use LexxSoft\odata\Traits\Restable;

class Log extends Model
{
    use HasFactory, Restable;
}

OData features

• Metadata
• CRUD
  • Create
  • Read
  • Update
  • Delete
• OData Entity
• OData request
  • Resource path
    • Simple request (i.e. /odata/category)
    • Count request (i.e. /odata/category/$count)
    • Request by key (i.e. /odata/category(1))
    • Single field value request (i.e. /odata/category(1)/name)
    • Value request (i.e. /odata/category(1)/name/$value)
    • Nested entity request (i.e. /odata/category(1)/products)
    • Count nested entity (i.e. /odata/category(1)/products/$count)
    • Deep nested entity (i.e. /odata/category(1)/products(2)/supplier/address/city/$value)
  • System query options
    • $orderby
    • $top
    • skip
    • $filter
      • EQ
      • NE
      • GT
      • GE
      • LT
      • LE
      • AND
      • OR
      • NOT
      • substringof
      • endswith
      • startswith
    • $expand
      • Simple expand (i.e.$expand=products)
      • Deep expand (i.e. $expand=products/supplier)
      • Expand with count (i.e. $expand=products($count=true))
    • $select
    • $count=true (ex. $inlinecount)
  • Custom query options (i.e. /odata/products?x=y)

Data manipulations

Reading data

To read data, use GET request. Also, you can add parameters to your query from OData features section

GET /odata/role?$top=5

Reading user with ID = 1

GET /odata/user(1)

Updating data

To update data you should use PUT method. Then, fill request body by new data.

Request example:

PUT /odata/role(2)

{
  "name": "User role"
}

Updating relations

To update Many-To-Many relationship, you need pass array of ID's for relation field name

{
  "id": 2,
  "permissions": [
    5,
    6,
    7
  ]
}

Updating relations with pivot

Sometimes Many-To-Many table has additional fields. To update them, pass array of objects for relation field.

Note, key field is required.

 {
  "id": 2,
  "permissions": [
    {
      "id": 5,
      "author": "Larry"
    },
    {
      "id": 8,
      "author": "John"
    }
  ]
}

Creating data

To create new record, use POST request type

POST /odata/role

{
  "name": "New role"
}

Deleting data

To delete data, use DELETE request with record key

DELETE /odata/role(2)

Using custom controller methods

OData plugin can make almost all CRUD operation automatically. But some cases should be operated individually. To make it real, OData plugin will search controller for model in path /app/Http/Controllers with filename pattern <Singular entity name>Controller.php. If controller file found, second step will be search corresponding method in class controller. Methods name are same as for resource controller. Use table below to check method name for yore case:

HTTP method	Controller class method name
GET	index
POST	store
PUT	update
PATCH	update
DELETE	destroy

As example, you have User model and UserController for it. But, when you make odata http request, you use plural name like /odata/users. Be carefully with this part.

Data validation rules

Operations like create or update should validate data, which comes from client. for this purpose ValidationRulesGenerator class is used. It generate validation rules only for Restable model, using database fields description. And, by default, it generate rules only for fillable fields.

Spatie laravel permissions

If you use laravel-permission from Spatie, then Rolemodel and Permission model not use Restable trait by default. To make them RESTable, you should create yore own models (for example, via php artisam make:model command) and extends yore new models from \Spatie\Permission\Models\* models

/** Extended Role model */
namespace App\Models;

use Lexxsoft\Odata\Primitives\Restable;

class Role extends \Spatie\Permission\Models\Role
{
  use Restable;
}

/** Extended Permission model */
namespace App\Models;

use Lexxsoft\Odata\Traits\Restable;

class Permission extends \Spatie\Permission\Models\Permission
{
    use Restable;
}