chippyash/Simple-Accounts

Quality Assurance

Certified for PHP 5.5

See the Test Contract

What?

Provides a simple double entry accounting system, that can be used as a component in a larger application.

Features

• Chart of Accounts (see here for a reasonable explanation)

  • You can define your own chart structures

• Account types

  • DR
    • ASSET
      • BANK
      • CUSTOMER
    • EXPENSE
  • CR
    • INCOME
    • LIABILITY
      • EQUITY
      • SUPPLIER

• Ability to save and retrieve a Chart through a simple interface

• Organisation concept that can have multiple Chart of Accounts

• Fantasy currencies are catered for

The library is released under the GNU GPL V3 or later license

Commercial licenses are available

Why?

Whilst full blown accounting systems are available, requiring a massive integration effort, some applications simply need to be able keep some form of internal account. This library is the direct descendant of something I wrote for a client many years ago to keep account of game points earned on a web site. Using the double entry accounting paradigm allowed the site owner to keep track of who had gathered points, and in which ways, whilst at the same time seeing what this meant to their business as game points translated into real world value for the customer by way of discounts and prizes.

When

The current library supports a Chart of Accounts.

Roadmap

• Journals
  • recording transactions
  • simplify transaction entries
  • closing accounts at year end
  • control accounts
• Reporting
  • balance sheet
  • trial balance
  • profit and loss

If you want more, either suggest it, or better still, fork it and provide a pull request.

See The Matrix Packages for other packages from chippyash

How

Coding Basics

Creating a new chart of accounts

Creating it manually

use chippyash\Accounts\Chart;
use chippyash\Accounts\Organisation;
use chippyash\Currency\Factory as Currency;
use chippyash\Type\Number\IntType;
use chippyash\Type\String\StringType;

$org = new Organisation(new IntType(1), new StringType('Foo'), Currency::create('gbp'));
$chart = new Chart(new StringType('Foo Chart'), $org);

Using the Accountant

The Accountant is a useful 'person'! But as usual they come at a cost: they need a fileClerk to do some of the work for them, and you have to give them that as payment. A fileClerk implements the AccountStorageInterface. A simple example that allows saving of Charts as serialized PHP file is provided to get you started, but of course you can create your own.

use chippyash\Accounts\Accountant;
use chippyash\Accounts\Storage\Account\Serialized;

$fileClerk = new Serialized(new StringType('/path/To/My/Account/Store'));
$accountant = new Accountant($fileClerk);

To create a chart via the accountant you still need to tell it what organisation the new chart is for, and also which COA template you want to use. A simple 'personal accounts' template is provided, which is an XML file. You can create and supply your own.

use chippyash\Accounts\ChartDefinition;
use chippyash\Accounts\Organisation;
use chippyash\Type\String\StringType;
use chippyash\Type\Number\IntType;
use chippyash\Currency\Factory as Currency;

$def = new ChartDefinition(new StringType('/path/to/definitions/personal.xml'));
$org = new Organisation(new IntType(1), new StringType('Foo'), Currency::create('gbp'));
$chart = $accountant->createChart(new StringType('Name of Chart'), $org, $def);

Adding accounts to the chart

Once you have a chart you may want to add new accounts to it. If you have created one manually from scratch it will not have a root account, so you need to add that first. All accounts are identified by a 'nominal code' or id. This is of type Nominal (based on chippyash\Type\String\DigitType) and is a numeric string. You can use any nominal code structure you like, but make sure you give yourself enough room to add the accounts you want. Take a look at the definitions/personal.xml for some insight.

Accounts also need a type for the account. These are defined in the AccountType enum class and are simply created by calling the class constant as a method. See the link in the thanks section for more information about Enums.

• add a root account

use use chippyash\Accounts\Nominal;
use chippyash\Accounts\AccountType;

ac1 = new Account($chart, new Nominal('2000'), AccountType::ASSET(), new StringType('Asset'));
$chart->addAccount($ac)

• add a child account

ac2 = new Account($chart, new Nominal('2100'), AccountType::BANK(), new StringType('Bank'));
$chart->addAccount($ac, $ac1->getId())

Saving the chart

$accountant->fileChart($chart));

Fetching the chart

$chart = $accountant->fetchChart(new StringType('Name of Chart'));

Making entries into accounts

You can make debit and credit entries to any account. Obviously, to maintain double entry accounting rules, you'll generally make one of each for any transaction.

You don't need to keep track of accounts, simply get them from the chart using their id.

Whilst it is not enforced, you are advised to use the same currency that you used for your organisation when creating amounts to debit and credit.

//can be used in most situations
$amount = Currency::create($chart->getOrg()->getCurrencyCode(), 12.26);

//use this method if locale issues are important or you are using a fantasy currency
$amount = clone $chart->getOrg()->getCurrency();
$amount->setAsFloat(12.26);
//or use set() if you know your currency precision
$amount->set(1226);

$chart->getAccount(new Nominal('1000'))->debit($amount);
$chart->getAccount(new Nominal('2000'))->credit($amount);

Getting account values

All account values are expressed as chippyash\Currency\Currency objects.

• debit and credit amounts

$debitAsInt = $chart->getAccount(new Nominal('1000'))->getDebit()->get();
$debitAsFloat = $chart->getAccount(new Nominal('1000'))->getDebit()->getAsFloat()
echo $chart->getAccount(new Nominal('1000'))->getDebit()->display();
$creditAsInt = $chart->getAccount(new Nominal('1000'))->getCredit()->get();
$creditAsFloat = $chart->getAccount(new Nominal('1000'))->getCredit()->getAsFloat()
echo $chart->getAccount(new Nominal('1000'))->getCredit()->display();

• account balance

For all account types (excluding DUMMY and REAL) get the account balance:

$balanceAsInt = $chart->getAccount(new Nominal('1000'))->getBalance()->get();
$balanceAsFloat = $chart->getAccount(new Nominal('1000'))->getBalance()->getAsFloat();
echo $chart->getAccount(new Nominal('1000'))->getBalance()->display();

The balance respects the conventions of DR and CR accounts.:

• DR balance = dr-cr
• CR balance = cr-dr

Class diagram

Changing the library

1. fork it
2. write the test
3. amend it
4. do a pull request

Found a bug you can't figure out?

1. fork it
2. write the test
3. do a pull request

NB. Make sure you rebase to HEAD before your pull request

Or - raise an issue ticket.

Where?

The library is hosted at Github. It is available at Packagist.org

Installation

Install Composer

For production

    "chippyash/simple-accounts": "~1.0.0"

For development

Clone this repo, and then run Composer in local repo root to pull in dependencies

    git clone git@github.com:chippyash/Simple-Accounts.git Accounts
    cd Accounts
    composer update

To run the tests:

    cd Accounts
    vendor/bin/phpunit -c test/phpunit.xml test/

Thanks

Back in the day, when the first Simple Accounts was written, I had to write a lot of support code myself. In this version I have been able to take advantage of the work of others. As well as the normal suspects of PHPUnit and vfsStream for writing the test code, I'd like to highlight some others:

• PHP Enum : a neat implementation of enums for PHP
• Tree : A simple tree component that supports the visitor pattern allowing for easy extension

History

V1.0.0 Original release