Getting started
Overview
While Filament comes with virtually any tool you'll need to build great apps, sometimes you'll need to add your own functionality either for just your app or as redistributable packages that other developers can include in their own apps. This is why Filament offers a plugin system that allows you to extend its functionality.
Before we dive in, it's important to understand the different contexts in which plugins can be used. There are two main contexts:
- Panel Plugins: These are plugins that are used with Panel Builders. They are typically used only to add functionality when used inside a Panel or as a complete Panel in and of itself. Examples of this are:
- A plugin that adds specific functionality to the dashboard in the form of Widgets.
- A plugin that adds a set of Resources / functionality to an app like a Blog or User Management feature.
- Standalone Plugins: These are plugins that are used in any context outside a Panel Builder. Examples of this are:
- A plugin that adds custom fields to be used with the Form Builders.
- A plugin that adds custom columns or filters to the Table Builders.
Although these are two different mental contexts to keep in mind when building plugins, they can be used together inside the same plugin. They do not have to be mutually exclusive.
Important Concepts
Before we dive into the specifics of building plugins, there are a few concepts that are important to understand. You should familiarize yourself with the following before building a plugin:
The Plugin object
Filament v3 introduces the concept of a Plugin object that is used to configure the plugin. This object is a simple PHP class that extends the Filament\Support\Plugin class. This class is used to configure the plugin and is the main entry point for the plugin. It is also used to register Resources and Icons that might be used by your plugin.
While the plugin object is extremely helpful, it is not required to build a plugin. You can still build plugins without using the plugin object as you can see in the Building a Panel Plugin tutorial.
Info The Plugin object is only used for Panel Providers. Standalone Plugins do not use this object. All configuration for Standalone Plugins should be handled in the plugin's service provider.
Registering Assets
All asset registration, including CSS, JS and Alpine Components, should be done through the plugin's service provider in the packageBooted() method. This allows Filament to register the assets with the Asset Manager and load them when needed.
Creating a Plugin
While you can certainly build plugins from scratch, we recommend using the Filament Plugin Skeleton to quickly get started. This skeleton includes all the necessary boilerplate to get you up and running quickly.
Usage
To use the skeleton, simply go to the GitHub repo and click the "Use this template" button. This will create a new repo in your account with the skeleton code. After that, you can clone the repo to your machine. Once you have the code on your machine, navigate to the root of the project and run the following command:
php ./configure.php
This will ask you a series of questions to configure the plugin. Once you've answered all the questions, the script will stub out a new plugin for you, and you can begin to build your amazing new extension for Filament.
Upgrading existing plugins
Since every plugin varies greatly in its scope of use and functionality, there is no one size fits all approaches to upgrading existing plugins. However, one thing to note, that is consistent to all plugins is the deprecation of the PluginServiceProvider.
In your plugin service provider, you will need to change it to extend the PackageServiceProvider instead. You will also need to add a static $name property to the service provider. This property is used to register the plugin with Filament. Here is an example of what your service provider might look like:
class MyPluginServiceProvider extends PackageServiceProvider
{
public static string $name = 'my-plugin';
public function configurePackage(Package $package): void
{
$package->name(static::$name);
}
}
Helpful links
Please read this guide in its entirety before upgrading your plugin. It will help you understand the concepts and how to build your plugin.