Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@jeffgreco13
jeffgreco13 committed Jan 23, 2022
1 parent 198bbff commit 7abebec
Showing 1 changed file with 17 additions and 171 deletions.
188 changes: 17 additions & 171 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,107 +5,45 @@
[![GitHub Code Style Action Status](https://img.shields.io/github/workflow/status/jeffgreco13/filament-breezy/Check%20&%20fix%20styling?label=code%20style)](https://github.com/jeffgreco13/filament-breezy/actions?query=workflow%3A"Check+%26+fix+styling"+branch%3Amain)
[![Total Downloads](https://img.shields.io/packagist/dt/jeffgreco13/filament-breezy.svg?style=flat-square)](https://packagist.org/packages/jeffgreco13/filament-breezy)

The missing toolkit from Filament Admin with Breeze-like functionality. Includes login, registration, password reset, password confirmation, email verification, my profile page, and teams. All using the TALL-stack, all very Filament-y.
The missing toolkit from Filament Admin with Breeze-like functionality. Includes login, registration, password reset, password confirmation, email verification, and a my profile page. All using the TALL-stack, all very Filament-y.

## Quick Start

This package works out-of-the-box with next to no configuration. To get started quickly, run the following command:

```bash
composer require jeffgreco13/filament-breezy && php artisan vendor:publish --tag="filament-breezy-migrations" && php artisan migrate
```

This will install the package, then publishes and runs the migrations.
Then, [add the `UserIsBreezy` trait](#installation) to your User model and that's it!

For more options, follow the Full Installation instructions below.

## Full Installation
## Installation

1. Install the package via composer:

```bash
composer require jeffgreco13/filament-breezy
```

2. Publish the config file, then update models and table names BEFORE running your migrations.

```bash
php artisan vendor:publish --tag="filament-breezy-config"
```

3. Publish the migrations:

```bash
php artisan vendor:publish --tag="filament-breezy-migrations"
```

4. Run the migrations to create the Teams tables:

```bash
php artisan migrate
```

5. Add the `UserIsBreezy` trait to your User model:
2. Update the `config/filament.php` to point to the Breezy Login::class.

```php
<?php namespace App;

use JeffGreco13\FilamentBreezy\Traits\UserIsBreezy;

class User extends Model
{
use UserIsBreezy; // Add this trait to your model
...
}
"auth" => [
"guard" => env("FILAMENT_AUTH_GUARD", "web"),
"pages" => [
"login" =>
\JeffGreco13\FilamentBreezy\Http\Livewire\Auth\Login::class,
],
],
```

6. Don't forget to dump composer autoload
Optionally, you can publish the Breezy config file for further customizations, such as Password rules, redirect after registration, and enable/disable the profile page.

```bash
composer dump-autoload
php artisan vendor:publish --tag="filament-breezy-config"
```

Optionally, you can publish the views using
Optionally, you can publish the views using:

```bash
php artisan vendor:publish --tag="filament-breezy-views"
```

## Usage

This package is extensively "borrowed" from the wonderful work of Marcel Pociot and the [Teamwork](https://github.com/mpociot/teamwork) package. You can get a full understanding of the capabilities by reviewing the [Teamwork docs](https://github.com/mpociot/teamwork#readme).

Similar to the `Teamwork` facade, you can access the same methods in the following way throughout your application:

```php
use JeffGreco13\FilamentTeams\FilamentTeams;

FilamentTeams::inviteToTeam($email, $team, function ($invite) {
// Send email to user / let them know that they got invited
});
```

### Auth

#### Login

The Login class extends Filament's login Livewire component. Update the Filament config to point to the Breezy Login::class.

```php
"auth" => [
"guard" => env("FILAMENT_AUTH_GUARD", "web"),
"pages" => [
"login" =>
\JeffGreco13\FilamentBreezy\Http\Livewire\Auth\Login::class,
],
],
```

#### Email Verification
### Email Verification

Uses the [Laravel Email Verification](https://laravel.com/docs/8.x/verification) service.

Implement `MustVerifyEmail` on your User model:

```php
Expand All @@ -122,7 +60,7 @@ Route::get("/profile", function () {
})->middleware("verified");
```

Or, force verified emails on your entire Filament Admin by adding the `EnsureEmailIsVerified` class to the auth middleware in Filament config:
Or, force verified emails on your entire Filament Admin by adding the `EnsureEmailIsVerified` class to the auth middleware in `config/filament.php`:

```php
"middleware" => [
Expand All @@ -133,7 +71,7 @@ Or, force verified emails on your entire Filament Admin by adding the `EnsureEma
....
```

#### Filament Livewire Components
### Extending and Overriding Components

All pages within the auth flow are full-page Livewire components made to work with Filament Forms. So you can easily extend any component to add your own fields and actions:

Expand Down Expand Up @@ -161,7 +99,7 @@ class Register extends FilamentBreezyRegister
...
```

#### Flash Notifications
### Flash Notifications

The Breezy auth layouts use the `<x-filament::notification>` component to flash messages to the page. Flash messages in the same way as you would with `$this->notify()` but instead flash to the session:

Expand All @@ -172,98 +110,6 @@ session()->flash("notify", [
]);
```

### User Model & Resource

With the `UserHasTeams` trait added to the User model, you expose many new methods including the `teams()` relationship.
For example, to display a user's teams and the current team name in the resource table, you can add the following columns:

```php
Tables\Columns\BadgeColumn::make("current_team_id")->label(
"Current team"
)->getStateUsing(fn($record) => $record->currentTeam?->name),
Tables\Columns\TagsColumn::make("teams")->getStateUsing(
fn($record) => $record
->teams()
->pluck("name")
->toArray()
),
```

You can manage a User's current team and/or team associations with the following form components:

```php
Forms\Components\Select::make("current_team_id")
->label("Current team")
->options(fn($record) => $record->teams()->pluck("name", "id")),
Forms\Components\BelongsToManyMultiSelect::make("teams")
->relationship("teams", "name"),
```

### Custom Models, Resources & Widgets

You can extend any of the models, resources and widgets like so:

```php
use JeffGreco13\FilamentTeams\Resources\FilamentTeamResource;

class TeamResource extends FilamentTeamResource
{
protected static function getNavigationIcon(): string
{
return "heroicon-o-lock-open";
}

// You can override any Resource method to use your own instead of those provided by FilamentTeams
public static function getPages(): array
{
return [
"index" => Pages\ListUsers::route("/"),
"create" => Pages\CreateUser::route("/create"),
"edit" => Pages\EditUser::route("/{record}/edit"),
];
}
}
```

Then, simply update the path in your config file to override:

```php
"team_model" => JeffGreco13\FilamentTeams\Models\FilamentTeam::class,
...
"enable_team_resource" => false,
... etc.
```

The invitations_send_widget, by default, will only show to the current team's owner.

### Custom Configurations & Nuances

A few things to be aware of:

1. When a Team is deleted, this change does not cascade to `current_team_id` on the User model.
1. When a User is deleted, this change does not cascade to `owner_id` on the Team model.
1. The `current_team_id` value on the User model is not automatically set in any way. You are responsible for writing your own logic to control this.

#### Middleware

You can add the EnsureValidTeam middleware to your Filament config in the 'auth' array after Authenticate if you wish to circumvent a potential security issue. If the `current_team_id` column is set on the User model but the User is no longer a member of that Team, it will still load that information (security flaw). This middleware will attempt to load the next available team or set `current_team_id` to null.

You can also add the `TeamOwner` middleware if you want to limit Filament access to Owners of teams only.

If this doesn't quite fit your need, feel free to write your own middleware and include it here.

```php
"middleware" => [
"auth" => [
Authenticate::class,
...
\JeffGreco13\FilamentTeams\Http\Middleware\EnsureValidTeam::class,
...
\JeffGreco13\FilamentTeams\Http\Middleware\TeamOwner::class,
],
...
```

## Testing

```bash
Expand Down

0 comments on commit 7abebec

Please sign in to comment.