PHPackages                             actengage/media - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. actengage/media

ActiveLibrary[File & Storage](/categories/file-storage)

actengage/media
===============

A simple media management package for Laravel.

v1.0.1(1y ago)01.1kMITPHPPHP ^8.2

Since May 25Pushed 1y ago1 watchersCompare

[ Source](https://github.com/ActiveEngagement/media)[ Packagist](https://packagist.org/packages/actengage/media)[ RSS](/packages/actengage-media/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (8)Versions (8)Used By (0)

Media
=====

[](#media)

This package provides a unit tested API to manage different types of files which can be related to Eloquent models (many to many relationships). Each type of file can be associated to its own resource for additional processing and manipulation. For instance, images are processed with the `Image` resource and manipulated with [Intervention Image](https://image.intervention.io/). API's are provides for creating your own resources.

### Features

[](#features)

- `Media` Eloquent Model and Migrations.
- `Mediable` trait to relate any eloquent model to the `Media` model.
- `Resource` API to add support for additional types of media.
- `Plugin` API which adds optional features, like color extraction for images.
- Uses [File Storage](https://laravel.com/docs/9.x/filesystem) to manage files.
- Uses [Intervention Image](https://image.intervention.io/) to manage and manipulate images.
- Unit tested

Requirements
------------

[](#requirements)

- Laravel 9.x+
- PHP 8.x+
- Intervention Image 2.x+
- GD or Imagick

Getting Started
---------------

[](#getting-started)

*Install via Composer*

```
composer require actengage/media

```

*Publish the config file*

```
php artisan vendor:publish --tag=config

```

*Optional, publish the migration files*

```
php artisan vendor:publish --tag=config

```

Resource Factory
----------------

[](#resource-factory)

The resource factory provides a unified interface for creating a variety of resources. You can even create your own resource classes and register them in `config/media.php`. By default, there are two types of resources: `Image` and `File`. For instance, you could define an `Audio` or `Video` resource. Resources are processed in the order they are defined.

```
use Actengage\Media\Facades\Resource;
use Illuminate\Http\UploadedFile;

// Create a resource from a path.
$resource = Resource::path('some/file/path/image.jpeg');

// Create a resource from request() instance.
$resource = Resource::request('image');

// Create a resource from an \Illuminate\Http\UploadedFile instance.
$resource = Resource::make(
    new UploadedFile('some/file/path/image.jpeg', 'image.jpeg')
);
```

Resource Methods
----------------

[](#resource-methods)

Every resource share a set of standard methods. And each type of resource may define its own method. Methods are chainable.

```
use Actengage\Media\Facades\Resource;

// Chain methods on the Resource facade to build the resource.
// This will save the resource to the `public` disk in the `images`
// directory. This resource is assumed to be an image and will be
// filtered using `greyscale()`.
$resource = Resource::request('image')
    ->disk('public')
    ->directory('images')
    ->filename('renamed.jpeg')
    ->title('Hello World!')
    ->caption('This is my first resource.')
    ->greyscale();

// Save the resource to the disk and return the `Media` model.
$media = $resource->save();
```

Conditional Resource Methods
----------------------------

[](#conditional-resource-methods)

Sometimes you may not know what kind of resource you are creating. You can use the `is()` method to conditionally chain methods to a specific resource types. Use the key configuration in `config/media.php` for matching or fully qualified class name.

```
use Actengage\Media\Facades\Resource;
use Actengage\Media\Resources\Image;

$resource = Resource::request('image')
    // When the resource is an image, make it greyscale.
    ->is('image', function($resource) {
        $resource->greyscale();
    })
    // You may also use the literal class as a match...
    ->is(Image::class, function($resource) {
        $resource->greyscale();
    })
    // When the resource is a file, do something else...
    ->is('file', function($resource) {
        // Do something here...
    });
```

You may also need to check for `true` and `false` values before executing code on a resource. For these scenarios, you may use `when()` and `not()` methods to conditionally chain methods to the resource.

```
use Actengage\Media\Facades\Resource;
use Actengage\Media\Resources\Image;

$resource = Resource::request('image')
    // When the value is `true` execute the callback.
    ->when(true, function($resource) {
        // This will only be called when `true` is passed to the first argument.
    })
    // You may also use a callback to check for a `true` value.
    ->when(function($resource) {
        return true;
    }, function($resource) {
        // This will only be called when `true` is returned from the first callback.
    })
    // When the value is `false` execute the callback.
    ->not(false, function($resource) {
        // This will only be called when `false` is passed to the first argument.
    })
    // You may also use a callback to check for a `false` value.
    ->not(function($resource) {
        return false;
    }, function($resource) {
        // This will only be called when `false` is returned from the first callback.
    });

## Resource Context, Meta, Tags

Contextual data can be used to search and filter `Media` models.

```php
use Actengage\Media\Facades\Resource;

$resource = Resource::request('image');

// Context allows you to give a simple string to assign from context to
// resources. For example, if you want to notate a resource is an image.
$resource->context('image');

// Meta data is a key/value store that is saved as JSON in the database.
// Similar to context, but this allows you to associate custom meta data
// with a resource instance.
$resource->meta([
    'some_key' => 'Some value goes here.'
]);

// Meta can be also added using individual arguments.
$resource->meta('another_key', 'Another key goes here.');

// Tags add an array of keys as context to a resource.
$resource->tags(['a', 'b', 'c']);

// Tags can be added using individual arguments or an array.
$resource->tags('d', 'e', 'f');
```

Events
------

[](#events)

Similar to Eloquent events, `Resource` event handlers work the same way. There are two ways to bind events, globally to a `Resource` class, or on the instance of a resource. The difference is global event binding is handled for all resources, whereas the instance methods are only fired for that instance.

### Global Methods

[](#global-methods)

```
use Actengage\Resources\Image;

Image::creating(function($resource, $model) {
    // This method is fired for the every Image resource before it
    // has been saved, similar to the `creating` Eloquent event.
});

Image::created(function($resource, $model) {
    // This method is fired for the every Image resource after it
    // has been saved, similar to the `creating` Eloquent event.
});
```

### Instance Methods

[](#instance-methods)

```
$resource = Resource::request('image')
    ->creating(function($resource, $model) {
        // This method is fired for the resource instance before it
        // has been saved, similar to the `creating` Eloquent event.
    })
    ->created(function($resource, $model) {
        // This method is fired for the resource instance after it
        // has been saved, similar to the `created` Eloquent event.
    });
```

Query Scopes
------------

[](#query-scopes)

The `Media` model provides some convenient scopes for searching.

```
use Actengage\Media\Media;

// Search by one or more captions
Media::caption('Some Caption');
Media::caption('Some Caption', 'Another Caption');
Media::caption(['Some Caption', 'Another Caption']);

// Search by one or more contexts
Media::context('Some Context');
Media::context('Some Context', 'Another Context');
Media::context(['Some Context', 'Another Context']);

// Search by one or more disks
Media::disk('public');
Media::disk('public', 's3');
Media::disk(['public', 's3']);

// Search by one or more extensions
Media::extension('jpeg');
Media::extension('jpeg', 'jpg');
Media::extension(['jpeg', 'jpg']);

// Search by one or more filenames
Media::filename('a.jpeg');
Media::filename('a.jpeg', 'b.jpeg');
Media::filename(['a.jpeg', 'b.jpeg']);

// Search by one or more filesizes
Media::filesize(2500);
Media::filesize(2500, 3500);
Media::filesize([2500, 3500]);

// Search by meta key/values
Media::meta([
    'a' => 1,
    'b' => 2,
    'c' => 3
]);

// Search by one or more mime types
Media::mime('text/plain');
Media::mime('text/plain', 'text/html');
Media::mime(['text/plain', 'text/html']);

// Search by one or more tags
Media::tag('a');
Media::tag('a', 'b');
Media::tag(['a', 'b', 'c']);

// Alias to tag() is tags()
Media::tags('a', 'b');

// Search by one or more titles
Media::title('Some Title');
Media::title('Some Title', 'Another Title');
Media::title(['Some Title', 'Another Title']);

// Search records without one or more tags
Media::withoutTag('a');
Media::withoutTag('a', 'b');
Media::withoutTag(['a', 'b', 'c']);

// Alias to withoutTag() is withoutTags()
Media::withoutTags('a', 'b');
```

Mediable Trait
--------------

[](#mediable-trait)

The `Mediable` trait is used to associate `Media` models to your custom models. `Media` models are related using `morphToMany` relationships.

*Document.php*

```