chippyash / simple-accounts
Simple Double Entry Accounting
Installs: 446
Dependents: 0
Suggesters: 0
Security: 0
Stars: 37
Watchers: 6
Forks: 19
Open Issues: 1
Requires
- php: >=5.5
- chippyash/assembly-builder: >=1,<2
- chippyash/currency: >=3,<4
- chippyash/identity: >=1.0.2,<2
- chippyash/monad: >=1,<2
- chippyash/record-status: >=1.0.0,<2
- chippyash/strong-type: >=3.0.2,<5
- myclabs/php-enum: >=1.3.2,<2
- nicmart/tree: >=0.2.5,<1
Requires (Dev)
- mikey179/vfsstream: >=1.6.5,<2
- phpunit/phpunit: >=4.8,<5
README
Notice
This project has been stopped. There is not enough traction on it to warrant its continuance. If you want to take it over, please contact me. Or simply fork it and carry on.
Quality Assurance
The above badges and this documentation represent the current development branch.
As a rule, I don't push to GitHub unless tests, coverage and usability are acceptable.
This may not be true for short periods of time; on holiday, need code for some other
downstream project etc. If you need stable code, use a tagged version. For definitive
documentation for a tgged version, read the README file in that version.
See the Test Contract
End of life notice
In March 2018, developer support will be withdrawn from this library for PHP <5.6. Older versions of PHP are now in such little use that the added effort of maintaining compatibility is not effort effective. See PHP Version Stats for the numbers.
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
- ASSET
- CR
- INCOME
- LIABILITY
- EQUITY
- SUPPLIER
- DR
-
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
-
Extensible Journal system, allowing recording of account transactions
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 support Organisations, Charts of Account, Journals and Control Accounts.
Roadmap
- Accounting
- closing 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.
Check out ZF4 Packages for more packages
How
Coding Basics
Creating a new chart of accounts
Creating it manually
use SAccounts\Chart; use SAccounts\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 SAccounts\Accountant; use SAccounts\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 SAccounts\ChartDefinition; use SAccounts\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'. 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 SAccounts\Nominal; use SAccounts\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->id())
Saving the chart
$accountant->fileChart($chart));
Fetching the chart
In fetching a chart you need to know the id of the organisation that it belongs to
$chart = $accountant->fetchChart(new StringType('Name of Chart'), new IntType(1));
This allows you to create multiple COAs for an organisation, potentially allowing you to keep task specific COAs or COAs for different currencies.
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
Using Journals
Whilst an Account records the value state at any given point in time, and a Chart holds the state of a collection (tree) of accounts, a Journal is responsible for recording the transaction history that led to the current state of the Account.
You may use the library without using Journalling at all, but most systems will want a transaction history. The Accountant can make use of an optional 'Journalist' that implements the JournalStorageInterface to create, save and amend both a Journal and the transactions that it records.
You must first supply a Journalist in the form of a JournalStorageInterface. An example is provided, Accounts\Storage\Journal\Xml which stores the Journal and its transactions into an XML file. You can provide your own to store against any other storage mechanism that you want to use.
use SAccounts\Storage\Journal\Xml as Journalist; $accountant->setJournalist(new Journalist(new StringType('/path/to/my/journal/store/folder')));
Creating a Journal
use Chippyash\Currency\Factory as Currency; $journal = $accountant->createJournal(new StringType('My Journal'), Currency::create('gbp'));
Under most circumstances, you'll associate an Organisation, and a Chart with a Journal, so it makes sense to use the same Currency:
$journal = $accountant->createJournal(new StringType('My Journal'), $chart->getOrg()->getCurrency());
Fetching a Journal that you already made
use SAccounts\Storage\Journal\Xml as Journalist; $accountant->setJournalist(new Journalist(new StringType('/path/to/my/journal/store/folder'))); $journal = $accountant->fetchJournal();
You can also store a journal via the accountant if you amend its definition
Creating transactions in the journal
You can either manage the link between the Journal and the Chart yourself by calling
their appropriate store mechanisms (see the code, tests and diagrams for that,) or
more simply, ask the accountant to do it for you. In either case, you first of all
need a Transaction. Transactions are provided by way of the SAccounts\Transaction\SplitTransaction
and SAccounts\Transaction\SimpleTransaction
. SimpleTransaction
is provided as helper
for creating and writing out transactions that consist of a pair of balanced debit and credit
amounts.
use SAccounts\Transaction\SimpleTransaction; use SAccounts\Nominal; $drAc = new Nominal('0000'); $crAc = new Nominal('1000'); $amount = Currency::create($chart->getOrg()->getCurrencyCode(), 12.26); $txn = new SimpleTransaction($drAc, $crAc, $amount);
You can set an optional 4th parameter when creating a SimpleTransaction:
$txn = new SimpleTransaction($drAc, $crAc, $amount, new StringType('This is a note'));
By default the date and time for the transaction is set to now(). You can set an optional 5th parameter when creating a SimpleTransaction and supply a DateTime object of your own choosing.
$txn = new SimpleTransaction($drAc, $crAc, $amount, new StringType(''), new \DateTime('2015-12-03T12:14:30Z));
To record a transaction and update the chart of accounts you can now use the Accountant again:
$txn = $accountant->writeTransaction($txn, $chart, $journal); //or $accountant->writeTransaction($txn, $chart, $journal);
The Transaction will now have its transaction id set, which you can recover via:
$txnId = $txn->getId() //returns IntType
You don't need to save the Journal, as it is inherently transactional, but don't forget to save your Chart once you have finished writing transactions.
The full power of the transaction is provided by the SplitTransaction
. And remember,
that when you read transactions back from the journal they will be in SplitTransaction
format. A split transaction allows you to have, say, one debit entry and three credit
entries. As long as the total debit entry amounts equal the total credit entry
amounts, you have a balanced transaction, i.e. a valid double entry transaction.
With power comes a little more complexity, as you'd expect!
use SAccounts\Transaction\SimpleTransaction; use SAccounts\Transaction\Entry; use SAccounts\Nominal; use Chippyash\Type\String\StringType; use Chippyash\Currency\Factory as Currency; $txn = new SplitTransaction() // date == now(), note == '' $txn = new SplitTransaction(new DateTime()); $txn = new SplitTransaction(null, new StringType('foo')); $txn = new SplitTransaction(new DateTime(), new StringType('foo')); //the following is analogous to a SimpleTransaction $note = new StringType('foo bar'); $dt = new \DateTime(); $amount = Currency::create('gbp', 12.26); $txn = (new SplitTransaction($dt, $note)) ->addEntry(new Entry(new Nominal('0000'), $amount, AccountType::DR())) ->addEntry(new Entry(new Nominal('1000'), $amount, AccountType::CR()));
When creating an Entry, you need to tell it:
- which account to use
- how much
- whether to debit or credit
To create true split transaction, lets use the following example:
- bank account: 3001
- vat account: 6007
- items account: 9056
- total transaction £120.00, £100 for the item, £20 as VAT
$txn = (new SplitTransaction($dt, $note)) ->addEntry(new Entry(new Nominal('3001'), Currency::create('gbp', 120), AccountType::DR())) ->addEntry(new Entry(new Nominal('6007'), Currency::create('gbp', 20), AccountType::CR())) ->addEntry(new Entry(new Nominal('9056'), Currency::create('gbp', 100), AccountType::CR()));
On the whole it is a really bad idea to create an unbalanced transaction and you can
check this with checkBalance()
which returns true if the transaction is balanced else false.
You can also do a simple check to see if the transaction conforms to being simple
using the isSimple()
method:
$drAc = $txn->getDrAc(); if ($txn->isSimple()) { $actualDrAc = $drAc[0]; } else { //you have an array of debit accounts, so process them }
getCrAc()
gets the credit accounts on a transaction.
The getEntries()
method of a SplitTransaction returns a SAccounts\Transaction\Entries
collection of entries.
Control Accounts
In the sense of an accounting definition of Control
Accounts, the Simple Accounts Control Account
can certainly be used to point to an adjustment account
in your Chart. However, in practical use, Control Accounts have a more broadly defined
use; that of pointing to specific accounts within the Chart. So in this sense, the
Simple Accounts Control Account is simply a pointer to another account.
In programming terms, we set up a Collection (Control\Links
) of Control Accounts (Control\Link
).
Let's use an example:
You have a system in which you want generic cash transactions to go to specific accounts:
- cash to/from the 'bank' account
- purchases to the 'sundries' account
- sales to the 'cash sales' account
The problem is, that as your COA (or business) grows, the actual account in the COA that you want to use may change. By dereferencing the actual account with a Control Account, your main code can remain the same, yet allowing you to reconfigure at will.
use SAccounts\Control; $linkArray = [ new Control\Link(new StringType('bank'), new Nominal('1000')), new Control\Link(new StringType('sundries'), new Nominal('2000')), new Control\Link(new StringType('cash sales'), new Nominal('3000')), ]; $ctrlAcs = (new Control\Links($linkArray)); $txn = (new SplitTransaction($dt, $note)) ->addEntry($ctrlAcs->getLinkId(new StringType('bank')), Currency::create('gbp', 120), AccountType::DR())) ->addEntry($ctrlAcs->getLinkId(new StringType('cash sales')), Currency::create('gbp', 120), AccountType::CR())); $txn2 = (new SplitTransaction($dt, $note)) ->addEntry($ctrlAcs->getLinkId(new StringType('bank')), Currency::create('gbp', 90), AccountType::CR())) ->addEntry($ctrlAcs->getLinkId(new StringType('sundries')), Currency::create('gbp', 90), AccountType::DR()));
It is really as simple as that. I've not included a storage mechanism for Control Accounts on the basis, that it is likely that you'll dependency inject them into your application, however there is an XML XSD in the definitions folder, with an example XML file in the docs directory. In practice you may find yourself using a number of Control Account Collections in an application.
Class diagrams
Changing the library
- fork it
- write the test
- amend it
- do a pull request
Found a bug you can't figure out?
- fork it
- write the test
- 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": "~2"
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
License
This software library is released under the GNU GPL V3 or later license
This software library is Copyright (c) 2015-2018, Ashley Kitson, UK
A commercial license is available for this software library, please contact the author. It is normally free to deserving causes, but gets you around the limitation of the GPL license, which does not allow unrestricted inclusion of this code in commercial works.
History
V1.0.0 Original release
V1.1.0 Journals added
V1.2.0
- replaced chippyash\Accounts namespace with SAccounts
- Transaction deprecated, use SimpleTransaction (Transaction proxies to SimpleTransaction and will be removed in the future)
- SplitTransactions introduced, use these for preference
- BC break with XML Journal file format to accommodate split transactions
V1.3.0 Added Control Accounts
V1.4.0 Update dependencies
V1.4.1 Add link to packages
V1.4.2 Verify PHP 7 compatibility
V1.4.3 Code cleanup
V1.4.4 Dependency update
V1.4.5 PhpUnit test suite update
V1.4.6 Update build script
V2.0.0 BC break in some interface definitions to support implementation of DB based systems.
V2.1.0 Add ability to set chart root node