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/.vitepress/theme/components/VersionSwitcher.vue b/.vitepress/theme/components/VersionSwitcher.vue deleted file mode 100644 index 2810ad2..0000000 --- a/.vitepress/theme/components/VersionSwitcher.vue +++ /dev/null @@ -1,226 +0,0 @@ - - - - - diff --git a/.vitepress/theme/index.ts b/.vitepress/theme/index.ts index 06171a9..a9948cc 100644 --- a/.vitepress/theme/index.ts +++ b/.vitepress/theme/index.ts @@ -1,7 +1,6 @@ import { h } from 'vue' import type { Theme } from 'vitepress' import DefaultTheme from 'vitepress/theme' -import VersionSwitcher from '@theme/components/VersionSwitcher.vue' import '@theme/styles/index.css' import '@theme/styles/custom.css' @@ -11,6 +10,5 @@ export default { return h(DefaultTheme.Layout, null, {}) }, enhanceApp({ app }) { - app.component('VersionSwitcher', VersionSwitcher) } } satisfies Theme diff --git a/src/master/architecture/panels.md b/src/master/architecture/panels.md index f9833bc..4cbb24c 100644 --- a/src/master/architecture/panels.md +++ b/src/master/architecture/panels.md @@ -62,17 +62,47 @@ The Admin [Panel](https://filamentphp.com/docs/3.x/panels/configuration) Provide - `sidebarCollapsibleOnDesktop()`: Makes the sidebar collapsible on desktop devices - `maxContentWidth()`: Sets content width to full screen -### Navigation Structure +## How Menus Are Registered + +Menus are registered through **Filament Resources, Pages, and Widgets** provided by each plugin. + +When a plugin is loaded: + +1. The **PluginManager** registers the plugin into the panel +2. Filament automatically discovers: + * Resources + * Pages + * Widgets +3. Each of these defines its own navigation configuration + +Example inside a Resource: + +```php +protected static ?string $navigationGroup = 'Sales'; +protected static ?string $navigationIcon = 'icon-orders'; +protected static ?int $navigationSort = 20; +``` + +This ensures: + +* The menu appears in the correct group +* The icon is consistent +* The menu order is predictable + +## Navigation Groups (High-Level Menu Sections) + +Navigation groups are **predefined at the panel level** in the `AdminPanelProvider`: ```php ->navigationGroups([ - NavigationGroup::make()->label('Dashboard'), - NavigationGroup::make()->label('Settings'), + NavigationGroup::make()->label(__('admin.navigation.sale')), + NavigationGroup::make()->label(__('admin.navigation.accounting')), + NavigationGroup::make()->label(__('admin.navigation.inventory')), ]) ``` -- Creates two main navigation groups: Dashboard and Settings -- Groups help organize navigation items into logical sections +These groups act as **containers**. +Plugins simply reference the group name when registering menus. ### Plugin Integration diff --git a/src/master/architecture/plugins.md b/src/master/architecture/plugins.md index 2aabe50..167fc2d 100644 --- a/src/master/architecture/plugins.md +++ b/src/master/architecture/plugins.md @@ -19,7 +19,8 @@ These plugin can be installed as needed to extend system functionality: | Module | Description | | ------------ | -------------------------------------------- | | Blogs | Manage blogs | -| Accounts | Financial accounting and reporting | +| Accounts | Core financial configuration module that defines chart of accounts, journals, ledgers, currencies, and fiscal structures used by other financial plugins | +| Accounting | Main accounting operations module that handles journal entries, financial reports, period closing, and accounting workflows based on the Accounts setup | | Contacts | Contact management for customers and vendors | | Employees | Employees management | | Inventory | Inventory and warehouse management | @@ -34,13 +35,38 @@ These plugin can be installed as needed to extend system functionality: | Timesheet | Employee work hour tracking | | Website | Website for customer | -## **Accounts** +## Accounts vs Accounting -- **Purpose**: Manages financial accounts, including ledgers, journals, and chart of accounts. -- **Key Features**: - - Supports multi-currency transactions. - - Integration with invoices and payments. - - Comprehensive financial reporting and audit trails. +In Aureus ERP, **Accounts** and **Accounting** are intentionally separated to provide a **flexible, scalable, and extensible financial system**. + +### **Accounts (Base / Helper Plugin)** + +* **Role**: Foundational financial layer +* **Purpose**: Provides core accounting structures used by other financial modules + +**Key Responsibilities:** + +* Chart of Accounts (assets, liabilities, income, expenses) +* Journals and ledger definitions +* Currency and fiscal configurations +* Common accounting utilities shared across modules + +The **Accounts plugin does not handle business workflows directly**. Instead, it acts as a **shared financial backbone** that ensures consistency across all financial operations. + +### **Accounting (Main Functional Plugin)** + +* **Role**: Primary accounting engine +* **Purpose**: Handles real-world accounting workflows and financial operations + +**Key Responsibilities:** + +* Journal entries and postings +* Financial reports (Profit & Loss, Balance Sheet, Trial Balance) +* Period closing and adjustments +* Integration with invoices, payments, purchases, and sales +* Audit trails and compliance-ready records + +The **Accounting plugin depends on Accounts** to function correctly and uses its structures to execute business logic. ## **Analytics** diff --git a/src/master/getting-started/clusters.md b/src/master/getting-started/clusters.md index dce38a7..3a17b61 100644 --- a/src/master/getting-started/clusters.md +++ b/src/master/getting-started/clusters.md @@ -17,18 +17,26 @@ To enable clusters in Aures ERP, configure the panel to discover cluster classes ```php public function register(Panel $panel): void { - if (! Package::isPluginInstalled($this->getId())) { - return; - } - $panel ->when($panel->getId() == 'admin', function (Panel $panel) { $panel - ->discoverResources(in: $this->getPluginBasePath('/Filament/Resources'), for: 'Webkul\\Blog\\Filament\\Resources') - ->discoverPages(in: $this->getPluginBasePath('/Filament/Pages'), for: 'Webkul\\Blog\\Filament\\Pages') + ->discoverResources( + in: __DIR__.'/Filament/Resources', + for: 'Webkul\\Blog\\Filament\\Resources' + ) + ->discoverPages( + in: __DIR__.'/Filament/Pages', + for: 'Webkul\\Blog\\Filament\\Pages' + ) // below method is responsible to discover the clusters form blog plugin. - ->discoverClusters(in: $this->getPluginBasePath('/Filament/Clusters'), for: 'Webkul\\Blog\\Filament\\Clusters') - ->discoverWidgets(in: $this->getPluginBasePath('/Filament/Widgets'), for: 'Webkul\\Blog\\Filament\\Widgets'); + ->discoverClusters( + in: __DIR__.'/Filament/Clusters', + for: 'Webkul\\Blog\\Filament\\Clusters' + ) + ->discoverWidgets( + in: __DIR__.'/Filament/Widgets', + for: 'Webkul\\Blog\\Filament\\Widgets' + ); }); } ``` diff --git a/src/master/getting-started/migrations.md b/src/master/getting-started/migrations.md index 15bc517..55fbce8 100644 --- a/src/master/getting-started/migrations.md +++ b/src/master/getting-started/migrations.md @@ -70,10 +70,10 @@ namespace Webkul\Blog; use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\Schema; -use Webkul\Support\Console\Commands\InstallCommand; -use Webkul\Support\Console\Commands\UninstallCommand; -use Webkul\Support\Package; -use Webkul\Support\PackageServiceProvider; +use Webkul\PluginManager\Console\Commands\InstallCommand; +use Webkul\PluginManager\Console\Commands\UninstallCommand; +use Webkul\PluginManager\Package; +use Webkul\PluginManager\PackageServiceProvider; class BlogServiceProvider extends PackageServiceProvider { diff --git a/src/master/getting-started/pages.md b/src/master/getting-started/pages.md index e1c72e3..f0b034b 100644 --- a/src/master/getting-started/pages.md +++ b/src/master/getting-started/pages.md @@ -125,7 +125,7 @@ use Filament\Contracts\Plugin; use Filament\Navigation\NavigationItem; use Filament\Panel; use Webkul\Blogs\Filament\Pages\Dashboard; -use Webkul\Support\Package; +use Webkul\PluginManager\Package; class BlogsPlugin implements Plugin { @@ -149,19 +149,19 @@ class BlogsPlugin implements Plugin ->when($panel->getId() == 'admin', function (Panel $panel) { $panel ->discoverResources( - in: $this->getPluginBasePath('/Filament/Resources'), + in: __DIR__.'/Filament/Resources', for: 'Webkul\Blogs\Filament\Resources' ) ->discoverPages( - in: $this->getPluginBasePath('/Filament/Pages'), + in: __DIR__.'/Filament/Pages', for: 'Webkul\Blogs\Filament\Pages' ) ->discoverClusters( - in: $this->getPluginBasePath('/Filament/Clusters'), + in: __DIR__.'/Filament/Clusters', for: 'Webkul\Blogs\Filament\Clusters' ) ->discoverWidgets( - in: $this->getPluginBasePath('/Filament/Widgets'), + in: __DIR__.'/Filament/Widgets', for: 'Webkul\Blogs\Filament\Widgets' ); }); @@ -171,11 +171,5 @@ class BlogsPlugin implements Plugin { // } - - protected function getPluginBasePath($path = null): string - { - $reflector = new \ReflectionClass(get_class($this)); - return dirname($reflector->getFileName()) . ($path ?? ''); - } } ``` diff --git a/src/master/getting-started/policies.md b/src/master/getting-started/policies.md index ba72442..18f5077 100644 --- a/src/master/getting-started/policies.md +++ b/src/master/getting-started/policies.md @@ -24,12 +24,12 @@ class PostPolicy public function viewAny(User $user): bool { - return $user->can('view_any_post'); + return $user->can('view_any_blogs_post'); } public function view(User $user, Post $post): bool { - return $user->can('view_post'); + return $user->can('view_blogs_post'); } } ``` @@ -88,6 +88,43 @@ These methods are used to determine a user's access level based on global, group | `hasIndividualAccess(User $user, Model $model, string $ownerAttribute = 'user'): bool` | Verifies if the user has access only to records they own. The `ownerAttribute` represents the ownership field in the model (default: `'user'`). | | `hasAccess(User $user, Model $model, string $ownerAttribute = 'user'): bool` | Evaluates all access levels (`global`, `group`, and `individual`) to determine if the user has the necessary permissions. The `ownerAttribute` defines the model's ownership field, defaulting to `'user'`. | +### How Policy Permissions Are Generated in Aureus ERP + +In Aureus ERP, **permission names** used in authorization policies are **automatically generated** by the `PermissionManager` leveraging **Filament Shield**. This approach ensures a consistent, modular, and conflict-free permission system across all plugins. + +### Why Policies Use the Plugin Namespace + +Policies are placed within each plugin’s own namespace (e.g., `Webkul\Blogs\Policies`) to keep authorization logic: + +* **Modular and Organized:** Each plugin manages its own models and policies separately. +* **Clear Ownership:** Policies are directly tied to the plugin’s models, simplifying maintenance. +* **Scalable:** Namespacing prevents clutter and collisions as more plugins are added. +* **Auto-Discovery Friendly:** Laravel and Filament automatically detect policies based on namespace conventions, reducing manual registration. + +This design helps Aureus ERP maintain a **clean, scalable, and well-structured permission system** throughout the platform. + +### Key Points About Permission Naming + +* Permissions include the **action**, **plugin name**, and **entity** to clearly scope access and prevent conflicts. +* The **plugin key** is extracted from the entity’s namespace (e.g., `Webkul\Blogs` becomes `blogs`). +* Different permission name formats are used depending on the entity type (Resource, Page, Widget, etc.). + +### Example Policy Methods and Permission Keys + +| Policy Method | Purpose | Permission Checked | Description | +| ------------- | --------------------------------- | --------------------- | ---------------------------------------------- | +| `viewAny` | Check if the user can list posts | `view_any_blogs_post` | Allows the user to view the posts listing page | +| `view` | Check if the user can view a post | `view_blogs_post` | Allows the user to view a specific post | + +--- + +This automatic permission naming system makes Aureus ERP’s authorization: + +* **Consistent:** Permission keys follow a clear naming convention. +* **Scalable:** Easily supports many plugins without collision. +* **Maintainable:** Simplifies policy writing and permission management. +* **Modular:** Keeps each plugin’s permissions isolated and organized. + ### **Example Usage in Policies** The following example demonstrates how to implement these access control methods within a policy: @@ -96,7 +133,7 @@ The following example demonstrates how to implement these access control methods public function update(User $user, Post $post): bool { // Check if the user has permission to update posts - if (! $user->can('update_post')) { + if (! $user->can('update_blogs_post')) { return false; } @@ -115,7 +152,7 @@ for example: ```php public function update(User $user, Post $post): bool { - if (! $user->can('update_post')) { + if (! $user->can('update_blogs_post')) { return false; } diff --git a/src/master/getting-started/seeders.md b/src/master/getting-started/seeders.md index b898544..2116bf3 100644 --- a/src/master/getting-started/seeders.md +++ b/src/master/getting-started/seeders.md @@ -118,8 +118,8 @@ To make Laravel recognize the Blog module’s seeder, register it inside the `Bl namespace Webkul\Blog; -use Webkul\Support\Package; -use Webkul\Support\PackageServiceProvider; +use Webkul\PluginManager\Package; +use Webkul\PluginManager\PackageServiceProvider; class BlogServiceProvider extends PackageServiceProvider { diff --git a/src/master/getting-started/settings.md b/src/master/getting-started/settings.md index 68e8d96..6e5a65e 100644 --- a/src/master/getting-started/settings.md +++ b/src/master/getting-started/settings.md @@ -178,10 +178,10 @@ namespace Webkul\Blog; use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\Schema; -use Webkul\Support\Console\Commands\InstallCommand; -use Webkul\Support\Console\Commands\UninstallCommand; -use Webkul\Support\Package; -use Webkul\Support\PackageServiceProvider; +use Webkul\PluginManager\Console\Commands\InstallCommand; +use Webkul\PluginManager\Console\Commands\UninstallCommand; +use Webkul\PluginManager\Package; +use Webkul\PluginManager\PackageServiceProvider; class BlogServiceProvider extends PackageServiceProvider { diff --git a/src/master/plugins/filament.md b/src/master/plugins/filament.md index 74de751..d03aa4d 100644 --- a/src/master/plugins/filament.md +++ b/src/master/plugins/filament.md @@ -22,24 +22,44 @@ The `register` method ensures that resources, pages, and clusters are only regis ```php public function register(Panel $panel): void { - if (! Package::isPluginInstalled($this->getId())) { - return; - } - $panel ->when($panel->getId() === 'customer', function (Panel $panel) { $panel - ->discoverResources(in: $this->getPluginBasePath('/Filament/Customer/Resources'), for: 'Webkul\\Blog\\Filament\\Customer\\Resources') - ->discoverPages(in: $this->getPluginBasePath('/Filament/Customer/Pages'), for: 'Webkul\\Blog\\Filament\\Customer\\Pages') - ->discoverClusters(in: $this->getPluginBasePath('/Filament/Customer/Clusters'), for: 'Webkul\\Blog\\Filament\\Customer\\Clusters') - ->discoverWidgets(in: $this->getPluginBasePath('/Filament/Customer/Widgets'), for: 'Webkul\\Blog\\Filament\\Customer\\Widgets'); + ->discoverResources( + in: __DIR__.'/Filament/Customer/Resources', + for: 'Webkul\\Blog\\Filament\\Customer\\Resources' + ) + ->discoverPages( + in: __DIR__.'/Filament/Customer/Pages', + for: 'Webkul\\Blog\\Filament\\Customer\\Pages' + ) + ->discoverClusters( + in: __DIR__.'/Filament/Customer/Clusters', + for: 'Webkul\\Blog\\Filament\\Customer\\Clusters' + ) + ->discoverWidgets( + in: __DIR__.'/Filament/Customer/Widgets', + for: 'Webkul\\Blog\\Filament\\Customer\\Widgets' + ); }) ->when($panel->getId() === 'admin', function (Panel $panel) { $panel - ->discoverResources(in: $this->getPluginBasePath('/Filament/Admin/Resources'), for: 'Webkul\\Blog\\Filament\\Admin\\Resources') - ->discoverPages(in: $this->getPluginBasePath('/Filament/Admin/Pages'), for: 'Webkul\\Blog\\Filament\\Admin\\Pages') - ->discoverClusters(in: $this->getPluginBasePath('/Filament/Admin/Clusters'), for: 'Webkul\\Blog\\Filament\\Admin\\Clusters') - ->discoverWidgets(in: $this->getPluginBasePath('/Filament/Admin/Widgets'), for: 'Webkul\\Blog\\Filament\\Admin\\Widgets'); + ->discoverResources( + in: __DIR__.'/Filament/Admin/Resources', + for: 'Webkul\\Blog\\Filament\\Admin\\Resources' + ) + ->discoverPages( + in: __DIR__.'/Filament/Admin/Pages', + for: 'Webkul\\Blog\\Filament\\Admin\\Pages' + ) + ->discoverClusters( + in: __DIR__.'/Filament/Admin/Clusters', + for: 'Webkul\\Blog\\Filament\\Admin\\Clusters' + ) + ->discoverWidgets( + in: __DIR__.'/Filament/Admin/Widgets', + for: 'Webkul\\Blog\\Filament\\Admin\\Widgets' + ); }); } ``` diff --git a/src/master/plugins/plugin.md b/src/master/plugins/plugin.md index 717e0de..9a6f88a 100644 --- a/src/master/plugins/plugin.md +++ b/src/master/plugins/plugin.md @@ -50,17 +50,41 @@ public function register(Panel $panel): void $panel ->when($panel->getId() == 'customer', function (Panel $panel) { $panel - ->discoverResources(in: $this->getPluginBasePath('/Filament/Customer/Resources'), for: 'Webkul\\Blog\\Filament\\Customer\\Resources') - ->discoverPages(in: $this->getPluginBasePath('/Filament/Customer/Pages'), for: 'Webkul\\Blog\\Filament\\Customer\\Pages') - ->discoverClusters(in: $this->getPluginBasePath('/Filament/Customer/Clusters'), for: 'Webkul\\Blog\\Filament\\Customer\\Clusters') - ->discoverClusters(in: $this->getPluginBasePath('/Filament/Customer/Widgets'), for: 'Webkul\\Blog\\Filament\\Customer\\Widgets'); + ->discoverResources( + in: __DIR__.'/Filament/Customer/Resources', + for: 'Webkul\\Blog\\Filament\\Customer\\Resources' + ) + ->discoverPages( + in: __DIR__.'/Filament/Customer/Pages', + for: 'Webkul\\Blog\\Filament\\Customer\\Pages' + ) + ->discoverClusters( + in: __DIR__.'/Filament/Customer/Clusters', + for: 'Webkul\\Blog\\Filament\\Customer\\Clusters' + ) + ->discoverClusters( + in: __DIR__.'/Filament/Customer/Widgets', + for: 'Webkul\\Blog\\Filament\\Customer\\Widgets' + ); }) ->when($panel->getId() == 'admin', function (Panel $panel) { $panel - ->discoverResources(in: $this->getPluginBasePath('/Filament/Admin/Resources'), for: 'Webkul\\Blog\\Filament\\Admin\\Resources') - ->discoverPages(in: $this->getPluginBasePath('/Filament/Admin/Pages'), for: 'Webkul\\Blog\\Filament\\Admin\\Pages') - ->discoverClusters(in: $this->getPluginBasePath('/Filament/Admin/Clusters'), for: 'Webkul\\Blog\\Filament\\Admin\\Clusters') - ->discoverClusters(in: $this->getPluginBasePath('/Filament/Admin/Widgets'), for: 'Webkul\\Blog\\Filament\\Admin\\Widgets'); + ->discoverResources( + in: __DIR__.'/Filament/Admin/Resources', + for: 'Webkul\\Blog\\Filament\\Admin\\Resources' + ) + ->discoverPages( + in: __DIR__.'/Filament/Admin/Pages', + for: 'Webkul\\Blog\\Filament\\Admin\\Pages' + ) + ->discoverClusters( + in: __DIR__.'/Filament/Admin/Clusters', + for: 'Webkul\\Blog\\Filament\\Admin\\Clusters' + ) + ->discoverClusters( + in: __DIR__.'/Filament/Admin/Widgets', + for: 'Webkul\\Blog\\Filament\\Admin\\Widgets' + ); }); } ``` @@ -76,18 +100,6 @@ public function boot(Panel $panel): void } ``` -### `getPluginBasePath($path = null): string` - -Returns the base path of the plugin, useful for dynamically locating directories. - -```php -protected function getPluginBasePath($path = null): string -{ - $reflector = new \ReflectionClass(get_class($this)); - return dirname($reflector->getFileName()) . ($path ?? ''); -} -``` - ## Adding Resources, Pages, Clusters, and Widgets - **Admin Panel (`admin`)**: Create the required Filament components inside `Filament/Admin/` diff --git a/src/master/plugins/resources.md b/src/master/plugins/resources.md index 0323c79..10fcd7a 100644 --- a/src/master/plugins/resources.md +++ b/src/master/plugins/resources.md @@ -35,10 +35,10 @@ namespace Webkul\Blog; use Filament\Support\Assets\Css; use Filament\Support\Facades\FilamentAsset; -use Webkul\Support\Console\Commands\InstallCommand; -use Webkul\Support\Console\Commands\UninstallCommand; -use Webkul\Support\Package; -use Webkul\Support\PackageServiceProvider; +use Webkul\PluginManager\Console\Commands\InstallCommand; +use Webkul\PluginManager\Console\Commands\UninstallCommand; +use Webkul\PluginManager\Package; +use Webkul\PluginManager\PackageServiceProvider; class BlogServiceProvider extends PackageServiceProvider { diff --git a/src/master/plugins/service-provider.md b/src/master/plugins/service-provider.md index 693e962..c412275 100644 --- a/src/master/plugins/service-provider.md +++ b/src/master/plugins/service-provider.md @@ -9,12 +9,12 @@ The service provider is the entry point for your plugin. It handles registration namespace Webkul\Blog; +use Filament\Panel; use Filament\Support\Assets\Css; use Filament\Support\Facades\FilamentAsset; -use Webkul\Support\Console\Commands\InstallCommand; -use Webkul\Support\Console\Commands\UninstallCommand; -use Webkul\Support\Package; -use Webkul\Support\PackageServiceProvider; +use Webkul\PluginManager\Console\Commands\InstallCommand; +use Webkul\PluginManager\Console\Commands\UninstallCommand; +use Webkul\PluginManager\PackageServiceProvider; class BlogServiceProvider extends PackageServiceProvider { @@ -52,6 +52,13 @@ class BlogServiceProvider extends PackageServiceProvider Css::make('blogs', __DIR__.'/../resources/dist/blogs.css'), ], 'blogs'); } + + public function packageRegistered(): void + { + Panel::configureUsing(function (Panel $panel): void { + $panel->plugin(AccountingPlugin::make()); + }); + } } ``` @@ -140,6 +147,36 @@ If you attempt to uninstall a plugin that other plugins depend on, you'll receiv Package website has dependents: blogs. Please uninstall dependents first! ``` +### Plugin Registration + +The `packageRegistered()` method is used to **register your plugin with the application panel** after the package is loaded. It ensures that the plugin is added **only when it is installed**, keeping the system modular and safe. + +```php +public function packageRegistered(): void +{ + Panel::configureUsing(function (Panel $panel): void { + $panel->plugin(AccountingPlugin::make()); + }); +} +``` + +#### Why this method is important + +* Registers the Filament plugin with the panel +* Prevents loading UI features when the plugin is not installed +* Avoids errors caused by missing migrations or settings +* Keeps plugin loading clean and dependency-aware + +#### When to use it + +Use `packageRegistered()` to: + +* Attach Filament plugins +* Configure panels conditionally +* Control when your plugin becomes visible in the admin UI + +In short, `packageRegistered()` is the **safe and correct place to register your plugin**, ensuring it loads only when the plugin is properly installed and ready to use. + ### Additional Configuration The `packageBooted()` method allows you to add additional configurations, such as registering CSS, JavaScript, or other resources: