optimuscms/media

v0.2 2019-04-30 08:57 UTC

Requires

• laravel/framework: ^5.7
• optimuscms/users: ^0.2
• optix/media: ^0.2

Requires (Dev)

• orchestra/testbench: ^3.7

MIT

• Jack Robertson

README

This package provides the core backend functionality within the CMS to upload media (image) files and organise them into folders.

Installation

This package can be installed through Composer.

composer require optimuscms/media

In Laravel 5.5 and above the package will autoregister the service provider.

In Laravel 5.4 you must install this service provider:

// config/app.php
'providers' => [
    ...
    Optimus\Media\MediaServiceProvider::class,
    ...
];

API Routes

The API follows standard RESTful conventions, with responses being returned in JSON. Appropriate HTTP status codes are provided, and these should be used to check the outcome of an operation.

Folders

• List folders
• Get folder
• Create folder
• Update folder
• Delete folder

Media Items

• List media items
• Get media item
• Create media item
• Update media item
• Delete media item

List folders

GET /admin/api/media-folders

List all available folders that media items can be added to.

Parameters

Parameter	Required?	Type	Description
parent	✗	int	A folder ID. When provided will only show folders nested inside this folder.

Example Response

[
    {
        "id": 12,
        "parent_id": null, 
        "name": "Product Images", 
        "created_at": "2017-12-24 09:36:23",
        "updated_at": "2017-12-25 10:15:12"
    },
    {
        "id": 13,
        "parent_id": 12, 
        "name": "Product Thumbnails", 
        "created_at": "2019-02-19 09:36:23",
        "updated_at": "2019-02-19 09:36:23"
    }
]

Get folder

GET /admin/api/media-folders/{id}

Retrieve details for a specific folder.

Parameters

Parameter	Required?	Type	Description
id	✓	int	The ID of the folder

Example Response

{
    "id": 12,
    "parent_id": null, 
    "name": "Product Images", 
    "created_at": "2017-12-24 09:36:23",
    "updated_at": "2017-12-25 10:15:12"
}

Update folder

PUT/PATCH /admin/api/media-folders/{id}

Update the details of a folder.

Parameters

Parameter	Required?	Type	Description
parent_id	✗	int	The ID of the parent folder. Set to empty to move the folder into the root
name	✗	string	The name of the folder

Example Response

{
    "id": 12,
    "parent_id": null, 
    "name": "Product Images", 
    "created_at": "2017-12-24 09:36:23",
    "updated_at": "2017-12-25 10:15:12"
}

Create folder

POST /admin/api/media-folders

Create a new folder.

Parameters

Parameter	Required?	Type	Description
parent_id	✓	int	The ID of the parent folder. Set to null to move the folder into the root
name	✓	string	The name of the folder

Example Response

{
    "id": 12,
    "parent_id": null, 
    "name": "Product Images", 
    "created_at": "2017-12-24 09:36:23",
    "updated_at": "2017-12-25 10:15:12"
}

Delete folder

DELETE /admin/api/media-folders/{id}

Delete a folder.

Parameters

Parameter	Required?	Type	Description
id	✓	int	The ID of the folder

Example Response

The HTTP status code will be 204 if successful.

List media items

GET /admin/api/media

List available media items.

Parameters

Parameter	Required?	Type	Description
folder	✗	int	Folder ID. When provided will only show media items from this folder.

Example Response

[
    {
        "id": 356,
        "folder_id": 12, 
        "name": "My Image", 
        "file_name": "my_image.jpg",
        "disk": "local",
        "mime_type": "image/jpeg", 
        "size": 102400,
        "created_at": "2017-12-24 09:36:23",
        "updated_at": "2017-12-25 10:15:12"
    },
    {
        "id": 513,
        "folder_id": 4, 
        "name": "Landscape", 
        "file_name": "landscape.png",
        "disk": "local",
        "mime_type": "image/png", 
        "size": 219462,
        "created_at": "2019-02-19 09:36:23",
        "updated_at": "2019-02-19 09:36:23"
    }
]

Get media item

GET /admin/api/media/{id}

Retrieve details of a specific media item.

Parameters

Parameter	Required?	Type	Description
id	✓	int	The ID of the media item

Example Response

{
    "id": 513,
    "folder_id": 4, 
    "name": "Landscape", 
    "file_name": "landscape.png",
    "disk": "local",
    "mime_type": "image/png", 
    "size": 219462,
    "created_at": "2019-02-19 09:36:23",
    "updated_at": "2019-02-19 09:36:23"
}

Update media item

PUT/PATCH /admin/api/media/{id} 

Update the details of a single media item.

Parameters

Parameter	Required?	Type	Description
name	✗	string	A user-facing name for the media item
folder_id	✗	int	The ID of the folder in which to store the media. If an empty value is provided, the media will be moved into the root folder.

Example Response

{
    "id": 513,
    "folder_id": 4, 
    "name": "Landscape", 
    "file_name": "landscape.png",
    "disk": "local",
    "mime_type": "image/png", 
    "size": 219462,
    "created_at": "2019-02-19 09:36:23",
    "updated_at": "2019-02-19 09:36:23"
}

Create media item

POST /admin/api/media

Create and store a new media item.

Parameters

Parameter	Required?	Type	Description
file	✓	file	The file that is being uploaded
folder_id	✗	int	The ID of the folder in which to store the media. If not provided, the media will be stored in the root folder.

Example Response

{
    "id": 513,
    "folder_id": 4, 
    "name": "Landscape", 
    "file_name": "landscape.png",
    "disk": "local",
    "mime_type": "image/png", 
    "size": 219462,
    "created_at": "2019-02-19 09:36:23",
    "updated_at": "2019-02-19 09:36:23"
}

Delete media item

DELETE /admin/api/media/{id}

Delete a media item.

Parameters

Parameter	Required?	Type	Description
id	✓	int	The ID of the media item to delete

Example Response

The HTTP status code will be 204 if successful.

License

The MIT License (MIT). Please see License File for more information.