From 6be3483ff4351b2b20376669ed88e40c57f9e284 Mon Sep 17 00:00:00 2001 From: Sandeep Chawla Date: Tue, 7 Oct 2025 11:22:25 +0530 Subject: [PATCH] `Updated FilamentPHP documentation links and references to version 4.x in various files.` --- .vitepress/config.ts | 1 - src/master/advanced/dashboard.md | 2 +- src/master/advanced/progress-stepper.md | 2 +- src/master/architecture/panels.md | 31 ++- src/master/architecture/plugins.md | 62 ++--- src/master/getting-started/clusters.md | 2 +- src/master/getting-started/pages.md | 2 +- .../resources/creating-record.md | 2 +- .../resources/editing-record.md | 2 +- .../resources/getting-started.md | 4 +- .../resources/listing-records.md | 2 +- .../resources/viewing-record.md | 2 +- src/master/getting-started/settings.md | 2 +- src/master/installation/installation.md | 13 +- src/master/plugins/filament.md | 64 ++++- src/master/prologue/introduction.md | 17 +- src/master/prologue/upgrade-guide.md | 234 +++++++++++++++--- 17 files changed, 349 insertions(+), 95 deletions(-) diff --git a/.vitepress/config.ts b/.vitepress/config.ts index e2e090c..4795857 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -71,7 +71,6 @@ export default defineConfig({ link: 'https://github.com/aureuserp/aureuserp' }, { text: 'Contact Us', link: 'https://aureuserp.com/en/contacts/' }, - { component: 'VersionSwitcher' } ], sidebar, diff --git a/src/master/advanced/dashboard.md b/src/master/advanced/dashboard.md index 8eea9ef..f35bb5b 100644 --- a/src/master/advanced/dashboard.md +++ b/src/master/advanced/dashboard.md @@ -198,4 +198,4 @@ public function getColumns(): int|string|array ## More Information -For more details, refer to the [FilamentPHP Dashboard Documentation](https://filamentphp.com/docs/3.x/panels/dashboard). +For more details, refer to the [FilamentPHP Dashboard Documentation](https://filamentphp.com/docs/4.x/panels/dashboard). diff --git a/src/master/advanced/progress-stepper.md b/src/master/advanced/progress-stepper.md index b68684b..a15e846 100644 --- a/src/master/advanced/progress-stepper.md +++ b/src/master/advanced/progress-stepper.md @@ -141,4 +141,4 @@ ProgressStepper::make('status') ## More Information -For more details, refer to the [FilamentPHP Toggle Buttons](https://filamentphp.com/docs/3.x/forms/fields/toggle-buttons). +For more details, refer to the [FilamentPHP Toggle Buttons](https://filamentphp.com/docs/4.x/forms/fields/toggle-buttons). diff --git a/src/master/architecture/panels.md b/src/master/architecture/panels.md index f9833bc..5a4196d 100644 --- a/src/master/architecture/panels.md +++ b/src/master/architecture/panels.md @@ -1,6 +1,6 @@ # Admin Panel Provider -The Admin [Panel](https://filamentphp.com/docs/3.x/panels/configuration) Provider configures the administrative backend interface using FilamentPHP. It establishes authentication mechanisms, visual components, middleware configurations, and plugin integrations for administrative users. +The Admin [Panel](https://filamentphp.com/docs/4.x/panels/configuration) Provider configures the administrative backend interface using FilamentPHP. It establishes authentication mechanisms, visual components, middleware configurations, and plugin integrations for administrative users. ## Configuration Breakdown @@ -34,14 +34,12 @@ The Admin [Panel](https://filamentphp.com/docs/3.x/panels/configuration) Provide ```php ->favicon(asset('images/favicon.ico')) -->brandLogo(asset('images/logo-light.svg')) -->darkModeBrandLogo(asset('images/logo-dark.svg')) +->brandLogo(asset('images/logo.svg')) ->brandLogoHeight('2rem') ``` - `favicon()`: Sets the browser tab icon -- `brandLogo()`: Defines the logo displayed in light mode -- `darkModeBrandLogo()`: Specifies an alternative logo for dark mode +- `brandLogo()`: Defines the logo displayed in the panel - `brandLogoHeight()`: Controls the displayed logo height ### User Experience Enhancements @@ -51,17 +49,28 @@ The Admin [Panel](https://filamentphp.com/docs/3.x/panels/configuration) Provide 'primary' => Color::Blue, ]) ->unsavedChangesAlerts() -->spa() -->sidebarCollapsibleOnDesktop() -->maxContentWidth(MaxWidth::Full) +->topNavigation() +->maxContentWidth(Width::Full) ``` - `colors()`: Defines the color scheme with blue as the primary color - `unsavedChangesAlerts()`: Warns users when trying to navigate away with unsaved changes -- `spa()`: Enables Single Page Application mode for smoother transitions -- `sidebarCollapsibleOnDesktop()`: Makes the sidebar collapsible on desktop devices +- `topNavigation()`: Enables horizontal navigation at the top - `maxContentWidth()`: Sets content width to full screen +### User Menu Configuration + +```php +->userMenuItems([ + 'profile' => Action::make('profile') + ->label(fn() => filament()->auth()->user()?->name) + ->url(fn(): string => Profile::getUrl()), +]) +``` + +- `userMenuItems()`: Adds custom items to the user menu in the top-right corner +- Creates a profile link that displays the user's name and navigates to the profile page + ### Navigation Structure ```php @@ -174,7 +183,7 @@ The Customer Panel Provider configures the frontend interface for customers, off ```php ->favicon(asset('images/favicon.ico')) -->brandLogo(asset('images/logo-light.svg')) +->brandLogo(asset('images/logo.svg')) ->darkMode(false) ->brandLogoHeight('2rem') ``` diff --git a/src/master/architecture/plugins.md b/src/master/architecture/plugins.md index ac94378..c9be0b9 100644 --- a/src/master/architecture/plugins.md +++ b/src/master/architecture/plugins.md @@ -1,6 +1,10 @@ -# Core Plugin (System Plugin) +# Plugins -These plugin are essential components of the system and are installed by default: +Plugins are the building blocks of Aureus ERP, encapsulating specific features and functionalities. Each plugin is designed to be modular, allowing for easy installation, removal, and customization. + +## Core Plugins (System Plugins) + +These plugins are essential components of the system and are installed by default: | Module | Description | | ---------- | ------------------------------------------------- | @@ -12,9 +16,9 @@ These plugin are essential components of the system and are installed by default | Support | Help desk and documentation | | Table View | Customizable data presentation framework | -## Installable Plugin +## Installable Plugins -These plugin can be installed as needed to extend system functionality: +These plugins can be installed as needed to extend system functionality: | Module | Description | | ------------ | -------------------------------------------- | @@ -22,7 +26,7 @@ These plugin can be installed as needed to extend system functionality: | Accounts | Financial accounting and reporting | | Contacts | Contact management for customers and vendors | | Employees | Employees management | -| Blogs | Inventory and warehouse management | +| Inventory | Inventory and warehouse management | | Invoices | Invoice generation and management | | Payments | Payment processing and tracking | | Products | Product catalog and management | @@ -31,10 +35,12 @@ These plugin can be installed as needed to extend system functionality: | Recruitments | Applicant tracking and hiring | | Sales | Sales pipeline and opportunity management | | Timeoffs | Leave management and tracking | -| Timesheet | Employee work hour tracking | +| Timesheets | Employee work hour tracking | | Website | Website for customer | -## **Accounts** +## Plugin Details + +### Accounts - **Purpose**: Manages financial accounts, including ledgers, journals, and chart of accounts. - **Key Features**: @@ -42,7 +48,7 @@ These plugin can be installed as needed to extend system functionality: - Integration with invoices and payments. - Comprehensive financial reporting and audit trails. -## **Analytics** +### Analytics - **Purpose**: Provides data visualization and insights for better decision-making. - **Key Features**: @@ -50,7 +56,7 @@ These plugin can be installed as needed to extend system functionality: - Customizable charts and reports. - Supports real-time data analysis. -## **Blogs** +### Blogs - **Purpose**: Manages content creation and publishing for company blogs. - **Key Features**: @@ -58,7 +64,7 @@ These plugin can be installed as needed to extend system functionality: - Role-based access for authors and editors. - Integration with the company website module. -## **Chatter** +### Chatter - **Purpose**: Collaborative messaging system for the app. - **Key Features**: @@ -66,7 +72,7 @@ These plugin can be installed as needed to extend system functionality: - Log notes, schedule activities, and send email notifications. - Polymorphic relationships to associate messages with any model. -## **Contacts** +### Contacts - **Purpose**: Centralized contact management system. - **Key Features**: @@ -74,21 +80,21 @@ These plugin can be installed as needed to extend system functionality: - Integration with sales and CRM modules. - Custom fields support for specific business needs. -## **Employees** +### Employees - **Purpose**: Manage employee information and profiles. - **Key Features**: - Role-based permissions and hierarchy management. - Tracks time-offs, timesheets, and attendance. -## **Fields** +### Fields - **Purpose**: Custom field management for dynamic data capture. - **Key Features**: - Add custom fields to any entity in the system. - Supports text, numbers, dropdowns, and file uploads. -## **Blogs** +### Inventory - **Purpose**: Track and manage stock levels across warehouses. - **Key Features**: @@ -96,35 +102,35 @@ These plugin can be installed as needed to extend system functionality: - Real-time stock updates linked to sales and purchases. - Integration with products and invoices. -## **Invoices** +### Invoices - **Purpose**: Generate and manage invoices for sales and services. - **Key Features**: - Supports recurring invoices and payment tracking. - Multi-currency and tax management. -## **Partners** +### Partners - **Purpose**: Manage relationships with business partners. - **Key Features**: - Tracks partnerships, agreements, and contact information. - Integration with sales and purchases. -## **Payments** +### Payments - **Purpose**: Tracks payments and receipts for financial transactions. - **Key Features**: - Multiple payment methods (cash, bank, online). - Reconciliation with accounts and invoices. -## **Products** +### Products - **Purpose**: Centralized product and service management. - **Key Features**: - Categorization and pricing rules. - Inventory tracking and integration with sales and purchases. -## **Projects** +### Projects - **Purpose**: Manage projects, tasks, and milestones. - **Key Features**: @@ -132,63 +138,63 @@ These plugin can be installed as needed to extend system functionality: - Time tracking and resource allocation. - Integration with chatter for communication. -## **Purchases** +### Purchases - **Purpose**: Manage procurement and vendor relations. - **Key Features**: - Generate purchase orders and manage approvals. - Vendor performance tracking. -## **Recruitments** +### Recruitments - **Purpose**: Streamline the hiring process. - **Key Features**: - Tracks job applications and candidate information. - Customizable recruitment workflows. -## **Sales** +### Sales - **Purpose**: Manage sales processes from lead generation to invoicing. - **Key Features**: - Quotation and order management. - Integration with CRM and analytics. -## **Security** +### Security - **Purpose**: Manage roles, permissions, and access control. - **Key Features**: - Role-based permissions using Spatie package. - Customizable security policies for data protection. -## **Support** +### Support - **Purpose**: Handle customer queries and issue resolution. - **Key Features**: - Ticketing system for support requests. - Automated reminders and escalation rules. -## **Table-Views** +### Table Views - **Purpose**: Unified table management system for list views. - **Key Features**: - Supports column filtering and sorting. - Customizable data grids for each module. -## **Timeoffs** +### Timeoffs - **Purpose**: Manage employee leave requests and approvals. - **Key Features**: - Leave balance tracking and policies. - Integration with payroll and employee modules. -## **Timesheets** +### Timesheets - **Purpose**: Record employee working hours and activities. - **Key Features**: - Weekly and daily views for time tracking. - Export timesheet data for payroll. -## **Website** +### Website - **Purpose**: Manage the company's website content. - **Key Features**: diff --git a/src/master/getting-started/clusters.md b/src/master/getting-started/clusters.md index dce38a7..d96258a 100644 --- a/src/master/getting-started/clusters.md +++ b/src/master/getting-started/clusters.md @@ -99,4 +99,4 @@ For better organization, store related resources and pages inside a directory ma ## More Information -For more details, refer to the [FilamentPHP Clusters Documentation](https://filamentphp.com/docs/3.x/panels/clusters). +For more details, refer to the [FilamentPHP Clusters Documentation](https://filamentphp.com/docs/4.x/panels/clusters). diff --git a/src/master/getting-started/pages.md b/src/master/getting-started/pages.md index e1c72e3..8d26f2a 100644 --- a/src/master/getting-started/pages.md +++ b/src/master/getting-started/pages.md @@ -34,7 +34,7 @@ The **Aureus ERP** Filament plugin provides robust project management capabiliti ## What are Filament Pages? -[Filament Pages](https://filamentphp.com/docs/3.x/panels/pages) are custom UI components that provide full-page interfaces within your admin panel. +[Filament Pages](https://filamentphp.com/docs/4.x/panels/pages) are custom UI components that provide full-page interfaces within your admin panel. ### Key Page Features in FilamentPHP diff --git a/src/master/getting-started/resources/creating-record.md b/src/master/getting-started/resources/creating-record.md index 325d51b..19e99ca 100644 --- a/src/master/getting-started/resources/creating-record.md +++ b/src/master/getting-started/resources/creating-record.md @@ -116,4 +116,4 @@ class CreatePost extends CreateRecord - **Post-Creation Processing**: Calls `updateStockLevels()` to recalculate stock availability after post creation. - **Redirection & Notifications**: Redirects to the post view and notifies the user on successful creation. -For more details, check the **[Official Filament Documentation](https://filamentphp.com/docs/3.x/panels/resources/creating-records)**. 🚀 +For more details, check the **[Official Filament Documentation](https://filamentphp.com/docs/4.x/panels/resources/creating-records)**. 🚀 diff --git a/src/master/getting-started/resources/editing-record.md b/src/master/getting-started/resources/editing-record.md index 52683ef..673440d 100644 --- a/src/master/getting-started/resources/editing-record.md +++ b/src/master/getting-started/resources/editing-record.md @@ -128,4 +128,4 @@ class EditPost extends EditRecord - **Actions**: Includes publish or unpublish, deletion, and Chatter integration for discussions. - **Redirection & Notifications**: Redirects to the post view and notifies the user on successful update. -For more details, check the **[Official Filament Documentation](https://filamentphp.com/docs/3.x/panels/resources/editing-records)**. 🚀 +For more details, check the **[Official Filament Documentation](https://filamentphp.com/docs/4.x/panels/resources/editing-records)**. 🚀 diff --git a/src/master/getting-started/resources/getting-started.md b/src/master/getting-started/resources/getting-started.md index b7e1e91..06f9d88 100644 --- a/src/master/getting-started/resources/getting-started.md +++ b/src/master/getting-started/resources/getting-started.md @@ -20,7 +20,7 @@ To generate a Filament resource, use the following command: php artisan make:filament-resource Post --view --model-namespace=Webkul\\Path\\Models ``` -for more information visit [Filament Official Documentation](https://filamentphp.com/docs/3.x/panels/resources/getting-started#creating-a-resource) +For more information visit [Filament Official Documentation](https://filamentphp.com/docs/4.x/panels/resources/getting-started#creating-a-resource) Upon execution, the command prompts you to select a panel: @@ -54,7 +54,7 @@ Once generated, the resource files will be located in: - `EditPost.php` - `ViewPost.php` (if enabled) -For more detailed documentation, refer to the official [Filament PHP Documentation](https://filamentphp.com/docs/3.x/panels/resources/getting-started). +For more detailed documentation, refer to the official [Filament PHP Documentation](https://filamentphp.com/docs/4.x/panels/resources/getting-started). ## **Anatomy of a Filament Resource** diff --git a/src/master/getting-started/resources/listing-records.md b/src/master/getting-started/resources/listing-records.md index 4d613e0..7165f30 100644 --- a/src/master/getting-started/resources/listing-records.md +++ b/src/master/getting-started/resources/listing-records.md @@ -81,4 +81,4 @@ public function getPresetTableViews(): array - Customize the **list page** to include actions like post creation. - Implement **preset views** for predefined post filters. -For more details, check the **[Official Filament Documentation](https://filamentphp.com/docs/3.x/panels/resources/listing-records)**. 🚀 +For more details, check the **[Official Filament Documentation](https://filamentphp.com/docs/4.x/panels/resources/listing-records)**. 🚀 diff --git a/src/master/getting-started/resources/viewing-record.md b/src/master/getting-started/resources/viewing-record.md index 021ef7d..df687b7 100644 --- a/src/master/getting-started/resources/viewing-record.md +++ b/src/master/getting-started/resources/viewing-record.md @@ -130,4 +130,4 @@ class ViewPost extends ViewRecord - **Chatter Integration**: Enables discussion around the post. - **Navigation Position**: Places the page navigation at the top. -For more details, check the **[Official Filament Documentation](https://filamentphp.com/docs/3.x/panels/resources/viewing-records)**. 🚀 +For more details, check the **[Official Filament Documentation](https://filamentphp.com/docs/4.x/panels/resources/viewing-records)**. 🚀 diff --git a/src/master/getting-started/settings.md b/src/master/getting-started/settings.md index 68e8d96..ebe794b 100644 --- a/src/master/getting-started/settings.md +++ b/src/master/getting-started/settings.md @@ -1,6 +1,6 @@ # **Settings Migrations** -[Spatie’s Laravel Settings](https://filamentphp.com/plugins/filament-spatie-settings) package provides a structured way to manage system-wide settings using a database instead of configuration files. It allows defining, storing, and retrieving settings dynamically, ensuring consistency across different environments. +[Spatie’s Laravel Settings](https://filamentphp.com/plugins/filament-spatie-laravel-settings) package provides a structured way to manage system-wide settings using a database instead of configuration files. It allows defining, storing, and retrieving settings dynamically, ensuring consistency across different environments. ## **Key Features of Spatie Laravel Settings** diff --git a/src/master/installation/installation.md b/src/master/installation/installation.md index bd68d70..cff030b 100644 --- a/src/master/installation/installation.md +++ b/src/master/installation/installation.md @@ -77,7 +77,17 @@ php artisan erp:install During the installation, you will be prompted to provide **Admin Login Credentials** (email and password). These credentials are used to log in to the admin panel. -## 8. Final Steps +## 8. Filament Installation Notes + +- Aureus ERP uses FilamentPHP, which introduces new features and improvements. +- Ensure your PHP version is compatible (PHP 8.2 or higher recommended). +- The installation process automatically sets up Filament Shield roles and permissions. +- Filament resources, pages, clusters, and widgets are registered separately for admin and customer panels. +- For plugin development, follow the new Filament resource registration structure. +- The `composer.json` includes a post-autoload-dump script that runs `php artisan filament:upgrade` to handle Filament upgrades. +- Refer to the [FilamentPHP documentation](https://filamentphp.com/docs/4.x) for detailed information. + +## 9. Final Steps Once the installation is complete, you can start the development server: @@ -92,3 +102,4 @@ http://127.0.0.1:8000 ``` That’s it! Your Aureus ERP environment is now ready to use. +php artisan serve diff --git a/src/master/plugins/filament.md b/src/master/plugins/filament.md index 74de751..4685271 100644 --- a/src/master/plugins/filament.md +++ b/src/master/plugins/filament.md @@ -1,12 +1,12 @@ # **Overview** -The `Filament` directory is used to define clusters, resources, and pages within the FilamentPHP panel. This structure allows for better organization and management of different sections in the plugin. +The `Filament` directory is used to define clusters, resources, pages, and widgets within the FilamentPHP panel. This structure allows for better organization and management of different sections in the plugin. For more details, refer to [Resources](../getting-started/resources/getting-started.md). ## **Types of Resource Registrations in the Plugin** -In the `BlogPlugin`, we register resources, pages, and clusters for two main panels: +In the `BlogPlugin`, we register resources, pages, clusters, and widgets for two main panels: 1. **Admin Panel** (`Admin` directory) 2. **Customer Panel** (`Customer` directory) @@ -15,11 +15,13 @@ Each panel has its own directory structure for managing Filament-related compone ## **Registering Resources and Clusters** -The `register` method ensures that resources, pages, and clusters are only registered if the plugin is installed. It also distinguishes between `admin` and `customer` panels, dynamically loading their respective components. +The `register` method ensures that resources, pages, clusters, and widgets are only registered if the plugin is installed. It also distinguishes between `admin` and `customer` panels, dynamically loading their respective components. ### **Implementation in `BlogPlugin.php`** ```php +use Filament\Panel; + public function register(Panel $panel): void { if (! Package::isPluginInstalled($this->getId())) { @@ -52,7 +54,7 @@ public function register(Panel $panel): void ## **Directory Structure** -To properly register resources, clusters, and pages, the following directory structure must be followed: +To properly register resources, clusters, pages, and widgets, the following directory structure must be followed: ``` +-- plugins @@ -72,10 +74,54 @@ To properly register resources, clusters, and pages, the following directory str ## **Usage Guidelines** -- **Admin Panel (`Admin` directory):** - - If you want to display resources and clusters in the **admin panel**, create your Filament components inside the `Admin` directory. +### **1. Admin Panel (`Admin` directory)** + +If you want to display resources, clusters, pages, or widgets in the **admin panel**, create your Filament components inside the `Admin` directory. + +Example: + +``` +plugins/blogs/Filament/Admin/Resources/PostResource.php +plugins/blogs/Filament/Admin/Pages/ManagePosts.php +``` + +These files will automatically be discovered and registered when the admin panel is initialized. + +--- + +### **2. Customer Panel (`Customer` directory)** + +If you want to display Filament components (resources, clusters, pages, or widgets) in the **customer panel**, create them inside the `Customer` directory. + +Example: + +``` +plugins/blogs/Filament/Customer/Resources/CommentResource.php +plugins/blogs/Filament/Customer/Pages/Dashboard.php +``` + +This ensures a clear separation between admin and customer functionalities. + + +## **Best Practices** + +* Keep **admin and customer logic isolated** for cleaner code maintenance. +* Always ensure your **namespace** matches the directory structure (e.g., `Webkul\\Blog\\Filament\\Admin\\Resources`). +* Regularly **clear and rebuild cache** after creating or modifying Filament components: + +```bash +php artisan optimize:clear +php artisan filament:cache +``` + +* If new components don’t appear in the panel, verify that: + + * The plugin is installed (`Package::isPluginInstalled()`). + * The directory paths in `discoverResources` match your folder structure. + * The namespaces are correct and autoloaded via Composer. + -- **Customer Panel (`Customer` directory):** - - If you want to show Filament resources and clusters in the **customer panel**, create them inside the `Customer` directory. +## **Conclusion** -By following this structure, Aureus ERP ensures clear separation between admin and customer functionalities, making the plugin more maintainable and scalable. +By following this directory structure and registration approach, **Aureus ERP** ensures that each plugin integrates seamlessly with FilamentPHP. +This pattern provides a clean, scalable way to manage both **admin** and **customer** panel functionalities — ensuring better organization, modularity, and future maintainability. diff --git a/src/master/prologue/introduction.md b/src/master/prologue/introduction.md index a27cac2..59cb33a 100644 --- a/src/master/prologue/introduction.md +++ b/src/master/prologue/introduction.md @@ -7,7 +7,7 @@ ## Key Features - **Powered by Laravel**: Ensures security, reliability, and scalability, making it ideal for enterprise-level applications. -- **Enhanced with FilamentPHP**: Delivers an intuitive admin panel, modular forms, and dynamic resource management for seamless interaction. +- **Enhanced with FilamentPHP**: Delivers an intuitive admin panel, modular forms, dynamic resource management, and improved performance for seamless interaction. - **Highly Modular Design**: Allows effortless integration of modules for finance, HR, inventory, CRM, and more, catering to diverse business needs. - **Open-Source & Extensible**: Freely available for use, modification, and extension, encouraging innovation within the developer community. - **Enterprise-Ready Scalability**: Designed to support complex workflows and business processes, making it adaptable to growing enterprises. @@ -20,4 +20,19 @@ - **Scalable & Customizable**: Easily tailored to fit the unique operational requirements of businesses of all sizes. - **Community-Driven Innovation**: Supported by an active open-source community, fostering continuous improvements, contributions, and support. +## Overview of FilamentPHP + +FilamentPHP introduces significant improvements over previous versions, including: + +- Enhanced performance and faster load times. +- Improved UI components with better accessibility and responsiveness. +- New resource registration APIs for cleaner and more flexible code. +- Advanced form and table components with richer features. +- Support for clusters and widgets to organize resources effectively. +- Better separation of admin and customer panels for tailored user experiences. +- Improved notifications, actions, and bulk operations. +- Enhanced extensibility for plugin development. + +Aureus ERP leverages these new features to provide a robust, scalable, and user-friendly ERP platform that is easy to extend and customize. + Aureus ERP is your gateway to an efficient, scalable, and highly customizable enterprise solution. Join the community and revolutionize the way you manage your business today! diff --git a/src/master/prologue/upgrade-guide.md b/src/master/prologue/upgrade-guide.md index 72ee199..e386f5d 100644 --- a/src/master/prologue/upgrade-guide.md +++ b/src/master/prologue/upgrade-guide.md @@ -1,83 +1,251 @@ # Upgrade Guide -## Upgrade Steps +This guide will help you upgrade your **Aureus ERP** installation to the latest version safely and efficiently. -To upgrade **Aureus ERP** to the latest version, follow these steps: +> **Important:** Always perform upgrades on a **staging or test environment** before updating your production instance. -### 1. Backup Your Project +--- -Before proceeding with the upgrade, ensure you **back up** your existing database and project files: +## Upgrade Methods -### 2. Pull the Latest Code +You can upgrade Aureus ERP using one of the following methods: -Navigate to your project’s root directory and pull the latest changes: +* [Upgrade via GitHub (Recommended for Developers)](#_2-upgrade-via-github) +* [Upgrade via Website Download (Recommended for Manual Installation)](#_3-upgrade-via-website-download) -```sh +--- + +## 1. Backup Your Project + +Before you begin, make sure to **back up** both your **database** and **project files**. + +### Database Backup + +```bash +# Example (MySQL) +mysqldump -u root -p aureus_db > backup_aureus_$(date +%F).sql +``` + +### Project Files Backup + +Copy your entire Aureus ERP directory as a backup: + +```bash +cp -r aureuserp aureuserp_backup_$(date +%F) +``` + +--- + +## 2. Upgrade via GitHub + +If you cloned the project using Git, follow these steps. + +### Step 1: Navigate to the Project Directory + +```bash +cd /path/to/aureuserp +``` + +### Step 2: Pull the Latest Code + +Pull the latest updates from the main repository: + +```bash git pull origin master ``` -If you have local changes that conflict with the update, you may need to **stash** them first: +If you have local modifications that conflict with the update, temporarily stash them: -```sh +```bash git stash git pull origin master -git stash pop # Restore stashed changes +git stash pop ``` -### 3. Update Dependencies +**GitHub Repository:** [https://github.com/aureuserp/aureuserp](https://github.com/aureuserp/aureuserp) + +--- -Once the latest code is pulled, update the dependencies: +## 3. Upgrade via Website Download -```sh +If you installed Aureus ERP manually (without Git), you can download the latest version from the official website. + +### Step 1: Download Latest Package + +Visit the official download page: +[https://aureuserp.com/download/](https://aureuserp.com/download/) + +### Step 2: Extract and Replace Files + +1. Extract the downloaded ZIP package. +2. Replace your existing Aureus ERP files, **except**: + + * `.env` + * `storage/` + * `vendor/` (will be regenerated) + * `public/storage` symlink + +### Step 3: Continue with the Dependency Update Steps Below + +--- + +## 4. Update Dependencies + +Once you have the latest code, update the Composer dependencies: + +```bash composer install --no-dev --optimize-autoloader ``` -If necessary, update Filament: +If you’re using Filament, update it as well: -```sh +```bash composer update filament/filament --with-dependencies ``` -### 4. Verify `.env` Configuration +**Note:** Aureus ERP includes a post-autoload script that automatically runs `php artisan filament:upgrade` to handle Filament v4 upgrades and compatibility changes. + +--- + +## 5. Verify `.env` Configuration + +Check your `.env` file and confirm that all configurations are correct: + +| Key | Description | +| ------------- | ---------------------------------- | +| `APP_URL` | The application URL | +| `APP_KEY` | Laravel application encryption key | +| `DB_DATABASE` | Database name | +| `DB_USERNAME` | Database user | +| `DB_PASSWORD` | Database password | + +If `.env` is missing, create it from the example file: + +```bash +cp .env.example .env +php artisan key:generate +``` + +Ensure your `.env` file has a valid `APP_KEY`, or you’ll see `Illuminate\Encryption\MissingAppKeyException`. -Check your **`.env`** file and ensure it contains the correct database and application settings. If necessary, update it to reflect any new configurations introduced in the latest version. +--- -### 5. Clear Cache and Recompile Assets +## 6. Clear Cache and Optimize -Run the following commands to clear cache and refresh your application settings: +Clean and rebuild all Laravel caches to ensure new configurations are applied: -```sh +```bash php artisan optimize:clear php artisan config:clear php artisan cache:clear php artisan view:clear ``` -### 6. Run Database Migrations +--- -Execute the migration command to apply any new database schema changes: +## 7. Run Database Migrations -```sh +Apply new database schema updates introduced in the latest version: + +```bash php artisan migrate ``` -::: warning -If your project has significant customizations, review the migrations carefully before running them. -::: +> **Caution:** If you have custom tables or modules, review migration files before applying them. + +--- -### 7. Update Storage and Symlink Public Assets +## 8. Update Storage and Symlink Public Assets -Ensure storage links are correctly set up by running: +Ensure your storage is properly linked: -```sh +```bash php artisan storage:link ``` -If your existing project depends on local storage or logs, copy them to the latest version: +If you maintain a backup of your storage directory, restore it: -```sh +```bash cp -r storage-backup/app/public storage/app/public ``` -Perform testing on all major features before deploying the upgraded git pull origin master -. +--- + +## 9. Test Your Application + +After the upgrade, thoroughly test the application: + +```bash +php artisan serve +``` + +Then visit your app in a browser: + +``` +http://127.0.0.1:8000 +``` + +Verify: + +* User authentication +* Dashboard & reports +* Custom modules or integrations +* File uploads and logs + +--- + +## 10. Troubleshooting + +If you encounter issues, try the following commands: + +```bash +php artisan config:clear +composer dump-autoload +php artisan optimize +``` + +Then check the Laravel log file for detailed error messages: + +```bash +storage/logs/laravel.log +``` + +### Common Issues + +| Issue | Cause | Solution | +| ------------------------ | --------------------------- | ------------------------------------------------------ | +| `MissingAppKeyException` | Missing `APP_KEY` in `.env` | Run `php artisan key:generate` | +| `Class not found` errors | Outdated dependencies | Run `composer install` | +| Debugbar slow load | Debugbar assets conflict | Disable Laravel Debugbar in `.env` (`APP_DEBUG=false`) | + +--- + +## 11. Restart Server or Services + +If you’re running the app under XAMPP, Valet, or Apache: + +* **XAMPP:** Restart Apache and MySQL from Control Panel. + +* **Artisan:** Stop and restart the built-in server: + + ```bash + php artisan serve + ``` + +* **Queue Workers:** Restart them after upgrading: + + ```bash + php artisan queue:restart + ``` + +--- + +## Conclusion + +You’ve successfully upgraded your **Aureus ERP** installation to the latest version. + +Stay up to date with new releases, patches, and community updates: + +* **GitHub Repository:** [https://github.com/aureuserp/aureuserp](https://github.com/aureuserp/aureuserp) +* **Official Website:** [https://aureuserp.com](https://aureuserp.com) +* **Download Page:** [https://aureuserp.com/download/](https://aureuserp.com/download/)