diff --git a/README.md b/README.md index 3147147..65b82ce 100644 --- a/README.md +++ b/README.md @@ -1,263 +1,87 @@ -# πŸš€ Laravel Filament Admin Starter Kit +# iMail - Temporary Email Service -A pre-configured **Laravel Admin Panel Starter Kit** built with [Livewire Starter Kit](https://github.com/laravel-livewire/starter-kit) and powered by [FilamentPHP](https://filamentphp.com/). +iMail is a simple, Laravel 12-based web application that provides a temporary email service. It allows users to create disposable email addresses to receive emails without revealing their personal email addresses. -Ideal for developers who want to skip boilerplate setup and jump straight into building robust admin dashboards, with essential tools and permissions already in place. +## Features ---- +- Create temporary email addresses. +- Receive and read emails sent to temporary addresses. +- Easy-to-use interface for checking received emails. +- Email addresses expire after a specified time or once accessed. -## ⚑ Features at a Glance +## Requirements -* βœ… Livewire Starter Kit foundation -* βœ… Elegant UI with **FilamentPHP** -* βœ… Filament Panel configurable via `.env` -* βœ… Roles & Permissions (Spatie) -* βœ… Activity Logging -* βœ… Mail & Log Viewer -* βœ… **Database Config Manager (via Filament Plugin)** -* βœ… Code quality with **RectorPHP** -* βœ… Authentication with default seeded admin +Before you start, ensure you have the following installed: ---- +- **PHP 8.1** or higher +- Composer +- Laravel 12.x +- MySQL or SQLite for the database -## πŸ“‚ Admin Panel Access +## Installation -* **Panel ID:** `dash` -* **Admin Route:** `/dash` (configurable) -* **Default Admin Credentials:** - -| Email | Password | -| ------------------- | ---------- | -| `admin@example.com` | `password` | - -> ⚠️ **Change these credentials before deploying to production.** - ---- - -## βš™οΈ Environment Configuration - -All major features are easily configurable using environment variables: - -```env -# Filament Admin Panel -FILAMENT_ROUTE=dash -FILAMENT_ENABLE_LOGIN=true -FILAMENT_ENABLE_REGISTER=false -FILAMENT_ENABLE_PROFILE=false - -# Activity Logger -ACTIVITY_LOGGER_ENABLED=true -ACTIVITY_LOGGER_TABLE_NAME=activity_log - -# Log Viewer -FILAMENT_LOG_VIEWER_DRIVER=raw -``` - ---- - -## 🎨 Filament Panel Configuration - -The Filament admin panel's appearance and basic behaviors are defined in `config/filament-php.php`: - -```php - env('FILAMENT_ROUTE', 'dash'), - - 'colors' => [ - 'primary' => Color::Teal, - 'danger' => Color::Red, - 'gray' => Color::Zinc, - 'info' => Color::Blue, - 'success' => Color::Green, - 'warning' => Color::Amber, - ], - - 'enable_login' => env('FILAMENT_ENABLE_LOGIN', true), - 'enable_registration' => env('FILAMENT_ENABLE_REGISTER', false), - 'enable_profile' => env('FILAMENT_ENABLE_PROFILE', false), -]; -``` - -You can easily override the route, theming colors, and feature toggles via `.env`. - ---- - -## πŸ” Roles & Permissions - -This starter kit uses [Spatie Laravel Permission](https://spatie.be/docs/laravel-permission) with the following default setup: - -### πŸ‘€ Roles - -* `admin` – Full control, including access to logs and mails -* `user` – No permissions assigned by default - -### πŸ”‘ Permissions - -The `admin` role is granted the following permissions: - -* `manage mails` -* `manage panels` - -These are assigned in the `RoleSeeder` class: - -```php -class RoleSeeder extends Seeder -{ - public function run(): void - { - $role = Role::findOrCreate(name: 'admin', guardName: 'web'); - Role::findOrCreate(name: 'user', guardName: 'web'); - - $permissionManageMails = Permission::findOrCreate(name: 'manage mails', guardName: 'web'); - $role->givePermissionTo($permissionManageMails); - - $permissionManageFilamentPanel = Permission::findOrCreate(name: 'manage panels', guardName: 'web'); - $role->givePermissionTo($permissionManageFilamentPanel); - } -} -``` - -> βœ… You can expand this by adding more roles and permissions via the Filament UI or custom seeders. - ---- - -## πŸ› οΈ Manage Config from Admin Panel (Inerba DB Config Plugin) - -This starter kit includes the [**Filament DB Config Plugin**](https://filamentphp.com/plugins/inerba-db-config) by **Inerba**, which allows you to **store application config settings in the database** and manage them from the admin panel. - -### πŸ”§ Features - -* Create configuration keys and values dynamically -* Group and categorize settings -* Easily retrieve values via `config('db-config.key')` -* No code deployment needed for config changes - -### 🧩 Usage - -After installing and publishing the plugin: - -1. Visit `/dash/db-config` in your Filament panel -2. Add new config entries (e.g. `site.name`, `maintenance_mode`, etc.) -3. Use in code like so: - -```php -$value = config('db-config.site.name'); -``` - -> ℹ️ Useful for managing site-wide settings, feature toggles, or any admin-editable config. - ---- - -## πŸ“¨ Mail Viewer - -View all outgoing mail inside the Filament admin panel β€” ideal for local and staging environments. - ---- - -## πŸͺ΅ Log Viewer - -Filament Log Viewer is pre-configured to use the `raw` driver: - -```env -FILAMENT_LOG_VIEWER_DRIVER=raw -``` - -View and analyze application logs from the admin panel. -For advanced configuration, see the [Log Viewer docs](https://github.com/ryangjchandler/filament-log). - ---- - -## πŸ•΅οΈ Activity Logger - -Tracks user actions and stores them in the `activity_log` table (or custom name via `.env`): - -```env -ACTIVITY_LOGGER_ENABLED=true -ACTIVITY_LOGGER_TABLE_NAME=activity_log -``` - -More configuration options available in [Spatie’s documentation](https://spatie.be/docs/laravel-activitylog). - ---- - -## 🧼 Automated Refactoring with Rector - -The root of the project includes a pre-configured `rector.php` file. -This allows for auto-refactoring and upgrading code to Laravel best practices. - -### βž• Run Rector: +### Step 1: Clone the Repository ```bash -vendor/bin/rector +git clone https://github.com/your-username/imail.git +cd imail ``` ---- +### Step 2: Install Dependencies -## πŸš€ Installation +Run the following command to install the required PHP dependencies: ```bash -git clone https://github.com/idevakk/starter-kit.git your-project -cd your-project - composer install +``` +### Step 3: Environment Configuration + +Copy the `.env.example` file to create your `.env` file: + +```bash cp .env.example .env +``` + +Edit the `.env` file and configure the database and other environment settings: + +```env +DB_CONNECTION=mysql +DB_HOST=127.0.0.1 +DB_PORT=3306 +DB_DATABASE=imail +DB_USERNAME=root +DB_PASSWORD= +``` + +### Step 4: Generate Application Key + +Generate the Laravel application key by running: + +```bash php artisan key:generate ``` -Update your `.env` with database and mail configuration: +### Step 5: Migrate the Database + +Run the database migrations to set up the required tables: + +```bash +php artisan migrate +``` + +### Step 6: Serve the Application + +Start the Laravel development server: ```bash -php artisan migrate --seed -npm install && npm run dev php artisan serve ``` -Visit: [http://localhost:8000/dash](http://localhost:8000/dash) (or your configured route) +Your application will be available at `http://127.0.0.1:8000`. ---- +## Usage -## πŸ“ Key Structure - -``` -β”œβ”€β”€ config/ -β”‚ β”œβ”€β”€ filament.php # Filament core settings -β”‚ β”œβ”€β”€ filament-php.php # UI theming + custom toggles -β”‚ β”œβ”€β”€ activitylog.php # Activity log config -β”‚ └── db-config.php # (Optional) Plugin config -β”œβ”€β”€ database/ -β”‚ └── seeders/FilamentAdminSeeder.php -β”‚ └── seeders/RoleSeeder.php -β”œβ”€β”€ rector.php # Rector config -``` - ---- - -## 🀝 Contributing - -Contributions are welcome. Feel free to fork, submit issues, or create pull requests. - ---- - -## πŸ›‘ License - -Open-sourced under the [MIT license](LICENSE). - ---- - -## πŸ™ Credits - -* [Laravel](https://laravel.com) -* [Livewire Starter Kit](https://github.com/laravel-livewire/starter-kit) -* [FilamentPHP](https://filamentphp.com/) -* [Spatie Permissions](https://github.com/spatie/laravel-permission) -* [Spatie Activity Log](https://spatie.be/docs/laravel-activitylog) -* [Filament Log Viewer](https://github.com/ryangjchandler/filament-log) -* [Filament Mail Viewer](https://github.com/ryangjchandler/filament-mail) -* [Inerba DB Config Plugin](https://filamentphp.com/plugins/inerba-db-config) -* [RectorPHP](https://getrector.com) - ---- +1. Go to the homepage of your application. +2. Create a temporary email address. +3. Use the email address to receive emails. +4. View received emails in the inbox section. diff --git a/package-lock.json b/package-lock.json index 945314b..61a3073 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,5 +1,5 @@ { - "name": "isms", + "name": "imail", "lockfileVersion": 3, "requires": true, "packages": {