PHPackages                             flowpack/media-ui - 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. [API Development](/categories/api)
4. /
5. flowpack/media-ui

ActiveNeos-package[API Development](/categories/api)

flowpack/media-ui
=================

This module allows managing media assets including pictures, videos, audio and documents.

3.1.1(2mo ago)2184.5k↑16.5%18[26 issues](https://github.com/Flowpack/media-ui/issues)[8 PRs](https://github.com/Flowpack/media-ui/pulls)2GPL-3.0-or-laterTypeScriptPHP ^8.2CI failing

Since Mar 15Pushed 2mo ago8 watchersCompare

[ Source](https://github.com/Flowpack/media-ui)[ Packagist](https://packagist.org/packages/flowpack/media-ui)[ Fund](https://shop.neos.io/neosfunding/onetime-badges/)[ RSS](/packages/flowpack-media-ui/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (14)Versions (64)Used By (2)

Neos Media UI
-------------

[](#neos-media-ui)

This package contains the new interface to manage media in Neos CMS (7.3 - 8.3).

During the initial development the package will be in the Flowpack namespace and will later replace `neos/media-browser`.

If you want to use Neos, please have a look at the [Neos documentation](http://neos.readthedocs.org/en/stable/).

Screenshots
-----------

[](#screenshots)

### Asset management

[](#asset-management)

### Asset selection

[](#asset-selection)

### Asset details

[](#asset-details)

Installation
------------

[](#installation)

Run the following command to install it:

```
composer require flowpack/media-ui
```

Afterward you should execute doctrine migrations, as the package adds new columns to the database:

```
./flow doctrine:migrate
```

In some rare cases it's necessary to flush the caches to prevent errors PHP errors, as the package extends some core classes:

```
./flow flow:cache:flush
```

Then you should update the paths of existing asset collections:

```
./flow assetcollections:updatepaths
```

This is only necessary once after the installation. Afterward the paths will be updated automatically.

### What changes?

[](#what-changes)

This package will currently add a second media backend module called `Media (new)` and a new media selection screen for asset and image editors. The old media module will still be available until this package replaces it completely with a later, major release of Neos.

#### Disabling the old Media module

[](#disabling-the-old-media-module)

If you don't need the old Media module, you can disable it in `Settings.yaml`:

```
Neos:
  Neos:
    modules:
      management:
        submodules:
          media:
            # Disable the default media module and use the new media ui
            enabled: false
          mediaui:
            # Moves the new module to top
            position: start
```

#### Disabling the new media selection

[](#disabling-the-new-media-selection)

If you want to use this package in a real project you might want to disable the new media selection if it doesn't work as expected. You can do this by adding the following setting to your `Settings.yaml`:

```
Neos:
  Neos:
    Ui:
      frontendConfiguration:
        Flowpack.Media.Ui:
          useNewMediaSelection: false
```

#### Privileges

[](#privileges)

By default any editor (Neos.Neos:AbstractEditor) can access the new media module and manage assets, tags and collections.

To adjust the privileges you can use the following privilege targets for any role:

```
- privilegeTarget: 'Flowpack.Media.Ui:ManageAssets'
  permission: GRANT
- privilegeTarget: 'Flowpack.Media.Ui:ManageTags'
  permission: GRANT
- privilegeTarget: 'Flowpack.Media.Ui:ManageAssetCollections'
  permission: GRANT
```

#### Hierarchical asset collections

[](#hierarchical-asset-collections)

This package will enable a hierarchical asset collection structure via AOP (until the feature is in the Neos core). With this feature you can add a collection in another collection or assign existing ones to another and this way create a structure comparable with folders in your computer's file system.

It is recommended to enable the feature flag `limitToSingleAssetCollectionPerAsset` (see below) for a better experience - see below.

The package also provides the `\Flowpack\Media\Ui\Security\Authorization\Privilege\ReadHierarchicalAssetCollectionPrivilege`with the additional method `isInPath()`, which can be used to control access to the collections.

```
privilegeTargets:
  'Flowpack\Media\Ui\Security\Authorization\Privilege\ReadHierarchicalAssetCollectionPrivilege':
    'Some.Package:ReadSpecialAssetCollectionAndSubCollections':
      matcher: 'isInPath("/important-collections")'
  'Flowpack\Media\Ui\Security\Authorization\Privilege\ReadAssetPrivilege':
    'Some.Package:ReadSpecialAssets':
      matcher: 'isInCollectionPath("/important-collections")'
```

Optional features
-----------------

[](#optional-features)

### Limit assets to be only assigned to one AssetCollection

[](#limit-assets-to-be-only-assigned-to-one-assetcollection)

By limiting assets to only be in one collection you can enforce a more folder-like experience:

```
Neos:
  Neos:
    Ui:
      frontendConfiguration:
        Flowpack.Media.Ui:
          # Only allow a single asset collection selection per asset to treat collection like folders
          limitToSingleAssetCollectionPerAsset: true
```

### Fast asset usage calculation & unused assets view

[](#fast-asset-usage-calculation--unused-assets-view)

The default asset usage in Neos is very slow as it is calculated when at runtime. For that it checks your whole project where an asset might be used. For the new Media UI, a new method has been implemented via the package [Flowpack.Neos.AssetUsage](https://github.com/Flowpack/Flowpack.Neos.AssetUsage).

The package provides a service that stores all asset usage references in a database table (other storages can be implemented). After installing the package and its peer dependencies, you should therefore update the usage reference index:

```
./flow assetusage:update

```

You have to do this only once for each instance of the application, f.e. dev / staging / production. Afterwards the index will automatically be kept up-to-date. Make sure you run the command manually again after you run imports or change the content repository in any other unusual way. This will clean up any outdated usage.

You can now enable the feature via the following setting:

```
Neos:
  Neos:
    Ui:
      frontendConfiguration:
        Flowpack.Media.Ui:
          queryAssetUsage: true
```

Now the "delete" action for assets will be disabled if an asset is in use, and the filter dropdown contains a new item "Unused". Selecting it will switch the main view to show all unused assets.

### Customise usage details

[](#customise-usage-details)

The usage calculation mechanism in Neos already supports custom usage providers via the `AssetUsageStrategyInterface`. If your strategy implements this interface, the Media UI will show the usages separately for each strategy.

By also implementing the `UsageDetailsProviderInterface` you can provide a custom label for the strategy and also custom headers and values for each entry.

### Show similar assets

[](#show-similar-assets)

This package provides a `SimilarAssetStrategyInterface`. Other packages can implement this interface and provide a list of other assets based on a given asset.

Example for this could be perceptually similar images or assets with similar filenames.

Given that you installed a package with a strategy, enable the feature in the ui with the following setting:

```
Neos:
  Neos:
    Ui:
      frontendConfiguration:
        Flowpack.Media.Ui:
          showSimilarAssets: true
```

### Disable asset redirect checkbox

[](#disable-asset-redirect-checkbox)

If you don't want to or can't use the automatic generation of redirects for assets, you can disable it with the following setting:

```
Neos:
  Neos:
    Ui:
      frontendConfiguration:
        Flowpack.Media.Ui:
          createAssetRedirectsOption: false
```

Architecture
------------

[](#architecture)

### API / GraphQL

[](#api--graphql)

This module introduces a GraphQL API for the Neos Media system. The API is open and can be reused for custom apps. A valid Neos backend user is required to access it, but you can define custom policies and an authentication provider to allow access without a user and f.e. use a token based authentication.

#### Schema

[](#schema)

The GraphQL schema can be found [here](Resources/Private/GraphQL/schema.root.graphql).

### Interface

[](#interface)

This module uses React for the implementation of the UI. Currently, most parts of the application are implemented as feature based packages in the `packages` folder. In future releases the code will be further split into smaller packages.

### State management

[](#state-management)

#### Query variables

[](#query-variables)

Query related state variables are stored via GraphQL Mutations in the Apollo Client Cache. Some of those variables are then persisted into the localstorage of the browser.

#### Resolved query result state

[](#resolved-query-result-state)

The MediaUI provider currently stores the results in its state and provides them to all child components via provider values. This will probably be changed to only set shared states that all components can access.

#### Component states

[](#component-states)

Component state should be stored with React hooks.

#### Shared component states

[](#shared-component-states)

The shared component states are current implemented via React [Recoil](https://recoiljs.org) atoms and selectors. See the `state` folders in the various modules in `packages` for examples.

Those should be used every time multiple components share a state that is not relevant for the GraphQL queries.

Fund the development
--------------------

[](#fund-the-development)

We need your help to develop this package. You can find supporter badges on the official [Neos funding site](https://shop.neos.io/neosfunding/onetime-badges/).

Contributing
------------

[](#contributing)

To start with development, make sure you have `nvm` and `yarn` installed and run the following command in the package's folder:

```
yarn
```

### Running the standalone dev server without Neos

[](#running-the-standalone-dev-server-without-neos)

The dev server allows to run the module without a Neos instance. This is also the basis for running most tests and implementing new features.

```
yarn dev
```

Enter `localhost:8000` in your browser, and you will have a running media ui instance without Neos.

### Building the module assets

[](#building-the-module-assets)

This will create a production build of the module assets.

```
yarn build
```

### Recompile files during development

[](#recompile-files-during-development)

The following command will recompile and reload the media module when changes to the scripts happen:

```
yarn watch
```

#### Only watch the backend module code

[](#only-watch-the-backend-module-code)

```
yarn watch:module
```

#### Only watch the UI plugin

[](#only-watch-the-ui-plugin)

```
yarn watch:editor
```

### Check for code quality

[](#check-for-code-quality)

Run the following command to verify the TypeScript files:

```
yarn lint
```

### Run e2e tests

[](#run-e2e-tests)

First start the dev server via `yarn dev` and the run the following command to execute all end-to-end tests:

```
yarn e2e
```

The test configuration is defined in `.testcaferc.json`.

To use a different browser, you can define it when running the tests:

```
yarn test firefox
```

Check out the [Testcafe documentation](https://testcafe.io/documentation/402828/guides/intermediate-guides/browsers#browser-support) for more information and supported browsers.

### Run phpstan for codestyle checks

[](#run-phpstan-for-codestyle-checks)

First, make sure you have [phpstan](https://phpstan.org) installed.

If the package is installed in a Neos distribution:

```
composer run codestyle
```

If the package is standalone

```
composer run codestyle:ci
```

### Run PHPUnit for unit tests

[](#run-phpunit-for-unit-tests)

If the package is installed in a Neos distribution:

```
composer run test
```

If the package is standalone

```
composer run test:ci
```

### Other development hints

[](#other-development-hints)

#### Before you commit

[](#before-you-commit)

Please don't add the compiled frontend assets to your commits/PRs.

We will build the assets when a new release is due.

If you want to build the assets for a release, use the following command to prevent cache issues:

```
yarn build:no-cache
```

#### Register additional icons

[](#register-additional-icons)

Font Awesome icons are registered in `packages/src/lib/FontAwesome`. This way the bundle size is kept to a minimum.

#### Patches

[](#patches)

Several [patches](.yarn/patches) are applied during installation via [patch-package](https://github.com/ds300/patch-package). Additional patches can be generated and stored there with the same tool if necessary.

#### Connection between the backend module and UI plugin

[](#connection-between-the-backend-module-and-ui-plugin)

The codebase is 99% reused between the backend module and the asset selection in the Neos UI. Make sure changes work in both worlds or provide a compatibility layer in the corresponding initialisation.

### Development helpers

[](#development-helpers)

- [Extension](https://github.com/apollographql/apollo-client-devtools) for debugging GraphQL schema and queries in the browser
- [Plugin](https://plugins.jetbrains.com/plugin/8097-js-graphql) for code completion and helpers in PHPStorm

License
-------

[](#license)

See [license](LICENSE).

###  Health Score

58

—

FairBetter than 98% of packages

Maintenance64

Regular maintenance activity

Popularity43

Moderate usage in the ecosystem

Community28

Small or concentrated contributor base

Maturity83

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 85.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~39 days

Recently: every ~25 days

Total

54

Last Release

81d ago

Major Versions

1.x-dev → 2.0.02025-07-11

2.0.0 → 3.0.02025-07-11

2.0.1 → 3.0.12025-09-16

2.0.2 → 3.0.22025-10-31

2.x-dev → 3.0.32025-11-19

PHP version history (4 changes)0.13.0-betaPHP ^7.4 || ^8.0

1.4.0PHP ^8.1

2.0.0-beta1PHP >=8.1

3.0.0-beta1PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/25d49a6af82b72d2764774a05c307808375016d7aeaaef3862472a6580ff38a7?d=identicon)[flowpack](/maintainers/flowpack)

---

Top Contributors

[![Sebobo](https://avatars.githubusercontent.com/u/596967?v=4)](https://github.com/Sebobo "Sebobo (788 commits)")[![dimaip](https://avatars.githubusercontent.com/u/837032?v=4)](https://github.com/dimaip "dimaip (30 commits)")[![grebaldi](https://avatars.githubusercontent.com/u/2522299?v=4)](https://github.com/grebaldi "grebaldi (20 commits)")[![suffle](https://avatars.githubusercontent.com/u/10942229?v=4)](https://github.com/suffle "suffle (17 commits)")[![markusguenther](https://avatars.githubusercontent.com/u/1014126?v=4)](https://github.com/markusguenther "markusguenther (16 commits)")[![pKallert](https://avatars.githubusercontent.com/u/91674611?v=4)](https://github.com/pKallert "pKallert (14 commits)")[![soee](https://avatars.githubusercontent.com/u/1798417?v=4)](https://github.com/soee "soee (7 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (7 commits)")[![dlubitz](https://avatars.githubusercontent.com/u/13046100?v=4)](https://github.com/dlubitz "dlubitz (7 commits)")[![daniellienert](https://avatars.githubusercontent.com/u/642226?v=4)](https://github.com/daniellienert "daniellienert (4 commits)")[![lorenzulrich](https://avatars.githubusercontent.com/u/1816023?v=4)](https://github.com/lorenzulrich "lorenzulrich (2 commits)")[![kdambekalns](https://avatars.githubusercontent.com/u/95873?v=4)](https://github.com/kdambekalns "kdambekalns (2 commits)")[![jannydiamond](https://avatars.githubusercontent.com/u/8681488?v=4)](https://github.com/jannydiamond "jannydiamond (2 commits)")[![jcarstens-cnlbz](https://avatars.githubusercontent.com/u/24565247?v=4)](https://github.com/jcarstens-cnlbz "jcarstens-cnlbz (1 commits)")[![ahaeslich](https://avatars.githubusercontent.com/u/1756367?v=4)](https://github.com/ahaeslich "ahaeslich (1 commits)")

---

Tags

graphqlhacktoberfestneos-cms

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/flowpack-media-ui/health.svg)

```
[![Health](https://phpackages.com/badges/flowpack-media-ui/health.svg)](https://phpackages.com/packages/flowpack-media-ui)
```

###  Alternatives

[nuwave/lighthouse

A framework for serving GraphQL from Laravel

3.5k10.7M93](/packages/nuwave-lighthouse)[thecodingmachine/graphqlite

Write your GraphQL queries in simple to write controllers (using webonyx/graphql-php).

5723.1M30](/packages/thecodingmachine-graphqlite)[wp-graphql/wp-graphql

GraphQL API for WordPress

3.8k391.7k19](/packages/wp-graphql-wp-graphql)[overblog/graphql-bundle

This bundle provides tools to build a GraphQL server in your Symfony App.

8027.9M28](/packages/overblog-graphql-bundle)[wheelpros/fitment-platform-api

Magento 2 (Open Source)

12.1k1.2k](/packages/wheelpros-fitment-platform-api)[aimeos/ai-admin-graphql

Aimeos Admin GraphQL API extension

944100.0k4](/packages/aimeos-ai-admin-graphql)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)