hxm/laravel-planning

Laravel Planing

v1.0.0 2024-12-24 03:21 UTC

Requires

• illuminate/database: ^7.0|^8.0|^9.0|^10.0|^11.0
• illuminate/support: ^7.0|^8.0|^9.0|^10.0|^11.0
• yajra/laravel-datatables-oracle: ^9.0

MIT

• HoanXuanMai

• laravel
• resource
• interval
• cycle
• planning
• laravel planning

README

Laravel Planning is a library that supports creating and managing plans in Laravel projects.

• Features
• Requirements
• Installation
• Configuration
  • Default Configurations
  • Directory Tree Representation
• Resource Management
• Implementing PlanResourceInstance
• Panel Management
  • Using the Panel
• Usage
  • Creating a Plan Order for a Resource
  • Managing Plan Cycles
  • Querying Resources with Cycles
• Contact
• Contribution
• License

Features

• Flexible plan and item management
• Event-driven actions and listeners
• Built-in scheduling and cron job support
• Customizable panel interface

Requirements

• PHP >= 7.4
• Laravel >= 7.x

Installation

Install the package via Composer:

composer require hxm/laravel-planning

Configuration

After installation, you can publish the configuration file using the following command:

php artisan vendor:publish --tag="laravel-planning:config"

You can also publish the migration files using:

php artisan vendor:publish --tag="laravel-planning:migration"

Default Configurations

Below are the default configurations:

<?php

use HXM\LaravelPlanning\Events;
use HXM\LaravelPlanning\Listeners;
use HXM\LaravelPlanning\Models;

return [
    "resources" => [
        // \App\User::class
    ], // string[] resource list
    "useMigration" => true,
    "tables" => [
        "prefix" => '',
        "plan" => 'plans',
        "item" => 'plan_items',
        "itemPercentPrice" => 'plan_item_percent_prices',
        "condition" => 'plan_conditions',
        "order" => 'plan_orders',
        "orderItem" => 'plan_order_items',
        "orderItemPercentPrice" => 'plan_order_item_percent_prices',
        "orderLog" => 'plan_order_logs',
        "cycle" => 'plan_cycles',
        "cycleItem" => 'plan_cycle_items',
        "cycleSchedule" => 'plan_schedules',
    ],
    "models" => [
        "plan" => Models\Plan::class,
        "item" => Models\PlanItem::class,
        "itemPercentPrice" => Models\PlanItemPercentPrice::class,
        "condition" => Models\PlanCondition::class,
        "order" => Models\PlanOrder::class,
        "orderItem" => Models\PlanOrderItem::class,
        "orderLog" => Models\PlanOrderLog::class,
        "cycle" => Models\PlanCycle::class,
        "cycleItem" => Models\PlanCycleItem::class,
    ],
    "listeners" => [
        Events\PlanOrderCreatedEvent::class => function (Events\PlanOrderCreatedEvent $event) {
            $event->planOrder->addLog('Created');
        },
        Events\PlanCycleCreatedEvent::class => [],
        Events\PlanCycleUpdatedStatusEvent::class => [
            Listeners\CreatePlanScheduleWhenCycleChangedStatus::class,
            function (Events\PlanCycleUpdatedStatusEvent $event) {
                $event->planCycle->planOrder->addLog('cycle#' . $event->planCycle->getKey() . ' change Status from ' . $event->preStatus . ' to ' . $event->planCycle->status, $event->planCycle->getReferable());
            }
        ],
    ],
    "schedule" => true,
    "cron" => '10 0 * * *',
    "pannel" => [
        "enable" => true,
        "prefix" => "plans",
        "as" => "plans.",
        "middleware" => ["web", "auth"]
    ]
];

Directory Tree Representation

Resource
├── PlanOrder (1-1)
│   ├── Plan (1-1)
│   │   ├── PlanItem (1-N)
│   │   │   ├── PlanItemPercentPrice (1-1)
│   │   │   ├── PlanCondition (1-1)
│   ├── OrderItem (1-N)
│   │   │   ├── PlanOrderItemPercentPrice (1-1)
│   │   │   ├── PlanCondition (1-1)
│   ├── PlanCycle (1-N)
│   │   ├── OrderItem (1-N)
│   │   └── CycleItem (1-N)
│   └── OrderLog (1-N)

Resource Management

The plans operate based on resource models. To create a plan for App\User, add it to the resources array in the configuration file:

"resources" => [
    \App\User::class
],

Alternatively, you can dynamically add resources in the AppServiceProvider:

use HXM\LaravelPlanning\LaravelPlanning;

public function boot()
{
    LaravelPlanning::addResources([\App\User::class]);
}

Implementing PlanResourceInstance

Before creating plan cycles for a resource (e.g., User), you must implement the PlanResourceInstance interface in your model and use the HasPlanResourceInstance trait:

use HXM\LaravelPlanning\Traits\HasPlanResourceInstance;
use HXM\LaravelPlanning\Contracts\PlanResourceInstance;

class User extends Authenticatable implements PlanResourceInstance
{
    use HasPlanResourceInstance;
}

Panel Management

Laravel Planning provides a built-in panel interface to manage plans. The panel settings are defined in the configuration under the pannel key:

"pannel" => [
    "enable" => true,
    "prefix" => "plans",
    "as" => "plans.",
    "middleware" => ["web", "auth"]
]

By default, the panel is enabled. You can disable it by setting "enable" to false. If the panel is disabled, you will need to create your own implementation for managing plans.

To access the panel, visit:

https://{yourhost}/plans

Using the Panel

1. Navigate to the Create section to create a new plan via the form.
2. Once a plan is created, add items to it. These items represent the features or content activated by the plan. Costs and prices can be set for each item.
3. If the cycle is set to 0, the items will repeat across cycles.

Usage

Here is an example of how to use the library:

Creating a Plan Order for a Resource

To create a plan order for a User resource:

use App\User;
use HXM\LaravelPlanning\Actions\Creations\CreatePlanOrderCalculator;
use HXM\LaravelPlanning\Models\Plan;

$user = User::find(1);
$plan = Plan::find(1);
$action = new CreatePlanOrderCalculator($user, $plan);

$startAt = now();
$numberOfCycle = 1;
$planOrder = $action->handle($startAt, $numberOfCycle);

// Save the plan order instance to the database
$planOrder->save();

// Get Items
$planOrder->getItems();

// Get Cycle list
$planOrder->getCycles();

// Optionally, initialize a payment for the plan order
// This can be done before or after saving the plan order.

Managing Plan Cycles

After saving the plan order, you can retrieve its cycles:

$planCycle = $planOrder->getCycles()->last();

You can associate a payment with the retrieved cycle:

$planCycle->referable()->associate($payment);
$planCycle->save();

By default, the plan cycle will have a status of inactive (status = 0). You can define your custom logic for handling this state.

To update the cycle's status, you can use:

use Illuminate\Database\Eloquent\Model;
use HXM\LaravelPlanning\Models\PlanCycle;
use HXM\LaravelPlanning\Actions\Updates\UpdatePlanCycleStatus;

UpdatePlanCycleStatus::handle(PlanCycle $planCycle,int $newStatus, Model $resource);
// Or
UpdatePlanCycleStatus::handleByReferable(Model $payment, int $newStatus);

When a cycle's status is updated to 1, a schedule is automatically created to generate the next cycle. The schedule's configuration is defined in the config file. You can listen for events such as PlanCycleCreatedEvent or PlanCycleUpdatedStatusEvent to add custom logic when new cycles are created or their statuses are updated.

Querying Resources with Cycles

You can query resources along with their current cycles:

$usersWithCurrentCycle = User::withCurrentCycle()->get();

Or retrieve a list of users with active cycles (status = 1):

$usersWithActiveCycle = User::hasActiveCycle()->get();

Contact

Please contact me if you need assistance Email.

You can also donate to me at Paypal

Contribution

We welcome contributions! Please follow these steps:

1. Fork the repository.
2. Create a new branch: git checkout -b new-feature.
3. Commit your changes: git commit -m 'Add new feature'.
4. Push to your branch: git push origin new-feature.
5. Submit a pull request.

License

This package is open-sourced software licensed under the MIT license.