README

Introduction

The dnj/laravel-account package provides easy way to manage accounts and transactions of the users in your app. The Package stores all data in the accounts and transactions table.

Latest versions of PHP and PHPUnit and PHPCsFixer
Best practices applied:
- README.md (badges included)
- LICENSE
- composer.json
- phpunit.xml
- .gitignore
- .php-cs-fixer.php
- Open Api 3
Some useful resources to start coding

Here's a demo of how you can use it:

use dnj\Account\Contracts\IAccount;
use dnj\Account\Contracts\IAccountManager;
use dnj\Account\Contracts\AccountStatus;
use dnj\Currency\Contracts\ICurrencyManager;

$currencyManager = app(ICurrencyManager::class);
$currency = $currencyManager->firstByCode("USD");

$accountManager = app(IAccountManager::class);

/**
 * @var IAccount $account
 */
$account = $accountManager->create(
    title: 'Profits',
    userId: Auth::user()->id,
    currencyId: $currency->getId(),
    status: AccountStatus::ACTIVE,
    canSend: true,
    canReceive: true,
    meta: ["key" => "value"],
    userActivityLog: true
);

Installation

You can install the package via composer:

composer require dnj/laravel-account

The package will automatically register itself.

After this you can create required tables by running the migrations:

php artisan migrate

You can optionally publish the config file with:

php artisan vendor:publish --provider="dnj\Account\AccountServiceProvider" --tag="config"

Config file:

return [
    // Define your user model class for connect accounts to users. Example: App\User:class
    'user_model' => null,
    
    // Enable http restful routes.
    'route_enable' => true,
    
    // Prefix of routes. By default routes register with /api/{prefix}/{accounts|transactions} pattern.
    'route_prefix' => null,
];

Working With Accounts

Create new account:

use dnj\Account\Contracts\IAccount;
use dnj\Account\Contracts\IAccountManager;
use dnj\Account\Contracts\AccountStatus;
use dnj\Currency\Contracts\ICurrencyManager;

$currencyManager = app(ICurrencyManager::class);
$currency = $currencyManager->firstByCode("USD");

$accountManager = app(IAccountManager::class);

/**
 * @var IAccount $account
 */
$account = $accountManager->create(
    title: 'Profits',
    userId: Auth::user()->id,
    currencyId: $currency->getId(),
    status: AccountStatus::ACTIVE,
    canSend: true,
    canReceive: true,
    meta: ["key" => "value"],
    userActivityLog: true
);

Update account:

use dnj\Account\Contracts\IAccountManager;
use dnj\Account\Contracts\AccountStatus;

$accountManager = app(IAccountManager::class);
$account = $accountManager->update(
    accountId: 2,
    changes: array(
        'status' => AccountStatus::DEACTIVE,
    ),
    userActivityLog: true
);

Destroy account:

use dnj\Account\Contracts\IAccountManager;

$accountManager = app(IAccountManager::class);
$accountManager->delete(
    accountId: $account->getId(),
    userActivityLog: true
);

Working With Transactions

Create transaction:

use dnj\Account\Contracts\IAccountManager;
use dnj\Account\Contracts\ITransactionManager;
use dnj\Account\Contracts\ITransaction;
use dnj\Number\Number;

$accountManager = app(IAccountManager::class);

$profits = $accountManager->getByID(1);
$salary = $accountManager->getByID(2);

$transactionManager = app(ITransactionManager::class);

/**
 * @var ITransaction $transaction
 */
$transaction = $transactionManager->transfer(
    fromAccountId: $profits->getId(),
    toAccountId: $salary->getId(),
    amount: Number::fromInput(2501.55),
    meta: [
        'month' => '2023-01'
    ],
    force: false,
    userActivityLog: true
);

Update transaction:

use dnj\Account\Contracts\ITransactionManager;
use dnj\Account\Contracts\ITransaction;

$transactionManager = app(ITransactionManager::class);

/**
 * @var ITransaction $transaction
 */
$transaction = $transactionManager->update(
    transactionId: 55,
    meta: [
        'month' => '2023-01',
        'over-time' => 21
    ]
);

Rollback transaction:

use dnj\Account\Contracts\ITransactionManager;
use dnj\Account\Contracts\ITransaction;

$transactionManager = app(ITransactionManager::class);

/**
 * @var ITransaction $rollbackTransaction new transaction that just made for rollback
 */
$rollbackTransaction = $transactionManager->rollback(55);

How to use package API

A document in YAML format has been prepared for better familiarization and use of package web services. which is placed in the openapi.json file.

To use this file, you can import it on the Swagger site and see all available methods.

Contribution

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

Testing

You can run unit tests with PHP Unit:

./vendor/bin/phpunit

About

We'll try to maintain this project as simple as possible, but Pull Requests are welcomed!

License

The MIT License (MIT). Please see License File for more information.

dnj / laravel-account

Maintainers

Details