Using custom properties | laravel-medialibrary | Spatie

 SPATIE

  Laravel Media Library
========================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-medialibrary](https://spatie.be/docs/laravel-medialibrary/v8)  Advanced-usage  Using custom properties

 Version   v11   v10   v9   v8   v7   v6   v5   v4   v3

 Other versions for crawler [v11](https://spatie.be/docs/laravel-medialibrary/v11) [v10](https://spatie.be/docs/laravel-medialibrary/v10) [v9](https://spatie.be/docs/laravel-medialibrary/v9) [v8](https://spatie.be/docs/laravel-medialibrary/v8) [v7](https://spatie.be/docs/laravel-medialibrary/v7) [v6](https://spatie.be/docs/laravel-medialibrary/v6) [v5](https://spatie.be/docs/laravel-medialibrary/v5) [v4](https://spatie.be/docs/laravel-medialibrary/v4) [v3](https://spatie.be/docs/laravel-medialibrary/v3)

- [ Introduction ](https://spatie.be/docs/laravel-medialibrary/v8/introduction)
- [ Support us ](https://spatie.be/docs/laravel-medialibrary/v8/support-us)
- [ Requirements ](https://spatie.be/docs/laravel-medialibrary/v8/requirements)
- [ Installation & setup ](https://spatie.be/docs/laravel-medialibrary/v8/installation-setup)
- [ Questions and issues ](https://spatie.be/docs/laravel-medialibrary/v8/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-medialibrary/v8/changelog)
- [ About us ](https://spatie.be/docs/laravel-medialibrary/v8/about-us)

Basic usage
-----------

- [ Preparing your model ](https://spatie.be/docs/laravel-medialibrary/v8/basic-usage/preparing-your-model)
- [ Associating files ](https://spatie.be/docs/laravel-medialibrary/v8/basic-usage/associating-files)
- [ Retrieving media ](https://spatie.be/docs/laravel-medialibrary/v8/basic-usage/retrieving-media)

Working with media collections
------------------------------

- [ Simple media collections ](https://spatie.be/docs/laravel-medialibrary/v8/working-with-media-collections/simple-media-collections)
- [ Defining media collections ](https://spatie.be/docs/laravel-medialibrary/v8/working-with-media-collections/defining-media-collections)

Converting images
-----------------

- [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v8/converting-images/defining-conversions)
- [ Retrieving converted images ](https://spatie.be/docs/laravel-medialibrary/v8/converting-images/retrieving-converted-images)
- [ Optimizing converted images ](https://spatie.be/docs/laravel-medialibrary/v8/converting-images/optimizing-converted-images)
- [ Naming conversion files ](https://spatie.be/docs/laravel-medialibrary/v8/converting-images/naming-conversion-files)
- [ Regenerating images ](https://spatie.be/docs/laravel-medialibrary/v8/converting-images/regenerating-images)

Responsive images
-----------------

- [ Getting started with responsive images ](https://spatie.be/docs/laravel-medialibrary/v8/responsive-images/getting-started-with-responsive-images)
- [ Using your own width calculator ](https://spatie.be/docs/laravel-medialibrary/v8/responsive-images/using-your-own-width-calculator)
- [ Customizing the rendered html ](https://spatie.be/docs/laravel-medialibrary/v8/responsive-images/customizing-the-rendered-html)
- [ Generating your own tiny placeholder ](https://spatie.be/docs/laravel-medialibrary/v8/responsive-images/generating-your-own-tiny-placeholder)
- [ Responsive images demo ](https://spatie.be/docs/laravel-medialibrary/v8/responsive-images/demo)

Downloading media
-----------------

- [ Downloading a single file ](https://spatie.be/docs/laravel-medialibrary/v8/downloading-media/downloading-a-single-file)
- [ Downloading multiple files ](https://spatie.be/docs/laravel-medialibrary/v8/downloading-media/downloading-multiple-files)

Converting other file types
---------------------------

- [ Using image generators ](https://spatie.be/docs/laravel-medialibrary/v8/converting-other-file-types/using-image-generators)
- [ Creating a custom image generator ](https://spatie.be/docs/laravel-medialibrary/v8/converting-other-file-types/creating-a-custom-image-generator)

Advanced usage
--------------

- [ Working with multiple filesystems ](https://spatie.be/docs/laravel-medialibrary/v8/advanced-usage/working-with-multiple-filesystems)
- [ Using custom properties ](https://spatie.be/docs/laravel-medialibrary/v8/advanced-usage/using-custom-properties)
- [ Storing media specific manipulations ](https://spatie.be/docs/laravel-medialibrary/v8/advanced-usage/storing-media-specific-manipulations)
- [ Using your own model ](https://spatie.be/docs/laravel-medialibrary/v8/advanced-usage/using-your-own-model)
- [ Rendering media ](https://spatie.be/docs/laravel-medialibrary/v8/advanced-usage/rendering-media)
- [ Using a custom directory structure ](https://spatie.be/docs/laravel-medialibrary/v8/advanced-usage/using-a-custom-directory-structure)
- [ Ordering media ](https://spatie.be/docs/laravel-medialibrary/v8/advanced-usage/ordering-media)
- [ Using a custom media downloader ](https://spatie.be/docs/laravel-medialibrary/v8/advanced-usage/using-a-custom-media-downloader)
- [ Moving media ](https://spatie.be/docs/laravel-medialibrary/v8/advanced-usage/moving-media)
- [ Consuming events ](https://spatie.be/docs/laravel-medialibrary/v8/advanced-usage/consuming-events)
- [ Generating custom urls ](https://spatie.be/docs/laravel-medialibrary/v8/advanced-usage/generating-custom-urls)
- [ Overriding default filesystem behavior ](https://spatie.be/docs/laravel-medialibrary/v8/advanced-usage/overriding-the-default-filesystem-behaviour)

API
---

- [ Adding files ](https://spatie.be/docs/laravel-medialibrary/v8/api/adding-files)
- [ Defining conversions ](https://spatie.be/docs/laravel-medialibrary/v8/api/defining-conversions)

      You are viewing the documentation for **an older version** of this package. You can check the version you are using with the following command:

 `                                    composer show spatie/laravel-medialibrary                                                                                                                                                                                                                                    `

Using custom properties
=======================

###  On this page

1. [ ZIP File Folders ](#content-zip-file-folders)

When adding a file to the media library you can pass an array with custom properties:

```
$mediaItem = $yourModel
    ->addMedia($pathToFile)
    ->withCustomProperties(['primaryColor' => 'red'])
    ->toMediaCollection();
```

There are some methods to work with custom properties:

```
$mediaItem->hasCustomProperty('primaryColor'); // returns true
$mediaItem->getCustomProperty('primaryColor'); // returns 'red'

$mediaItem->hasCustomProperty('does not exist'); // returns false
$mediaItem->getCustomProperty('does not exist'); // returns null

$mediaItem->setCustomProperty('name', 'value'); // adds a new custom property
$mediaItem->forgetCustomProperty('name'); // removes a custom property
```

It is also possible to filter a collection by a custom property using filters. These can either be a simple key value array or a callback to allow for more control:

```
$filteredCollection = $this->model->getMedia('images', ['primaryColor' => 'red']);

$filteredCollection = $this->model->getMedia('images', function (Media $media) {
    return isset($media->custom_properties['primaryColor']);
});

```

If you are setting or removing custom properties outside the process of adding media then you will need to persist/save these changes:

```
$mediaItem = Media::find($id);

$mediaItem->setCustomProperty('name', 'value'); // adds a new custom property or updates an existing one
$mediaItem->forgetCustomProperty('name'); // removes a custom property

$mediaItem->save();
```

You can also specify a default value when retrieving a custom property.

```
$mediaItem->getCustomProperty('isPublic', false);
```

If you're dealing with nested custom properties, you can use dot notation.

```
$mediaItem = $yourModel
    ->addMedia($pathToFile)
    ->withCustomProperties([
        'group' => ['primaryColor' => 'red']
    ])
    ->toMediaCollection();

$mediaItem->hasCustomProperty('group.primaryColor'); // returns true
$mediaItem->getCustomProperty('group.primaryColor'); // returns 'red'

$mediaItem->hasCustomProperty('nested.does-not-exist'); // returns false
$mediaItem->getCustomProperty('nested.does-not-exist'); // returns null
```

---

title: Special custom properties weight: 2

---

ZIP File Folders
--------------------------------------------------------------------------------------------------------

The ZIP export stores all media files in the root folder of the ZIP file.

If you want to save media in subfolders, you can do this with the help of the special custom property 'zip\_filename\_prefix'.

Each media can be assigned to a subfolder.

```
$mediaItem = Media::find($id);

$mediaItem->setCustomProperty('zip_filename_prefix', 'folder/subfolder/'); // stores $mediaItem in Subfolder

$mediaItem->save();

$mediaStream =  MediaStream::create('export.zip');
$mediaStream->addMedia($mediaItem);
```