Skip to content

Commit

Permalink
interface changes to support db transactional systems
Browse files Browse the repository at this point in the history
  • Loading branch information
Ashley Kitson committed Jan 7, 2018
1 parent e8b5d5c commit 30918b6
Show file tree
Hide file tree
Showing 21 changed files with 422 additions and 193 deletions.
2 changes: 0 additions & 2 deletions .travis.yml
View file
Expand Up @@ -3,8 +3,6 @@ language: php

# list any PHP version you want to test against
php:
# aliased to a recent 5.5.x version
- 5.5
# aliased to a recent 5.6.x version
- 5.6
# aliased to a recent 7.x version
Expand Down
134 changes: 79 additions & 55 deletions README.md
View file
Expand Up @@ -9,6 +9,12 @@
[![Test Coverage](https://codeclimate.com/github/chippyash/Simple-Accounts/badges/coverage.svg)](https://codeclimate.com/github/chippyash/Simple-Accounts/coverage)
[![Code Climate](https://codeclimate.com/github/chippyash/Simple-Accounts/badges/gpa.svg)](https://codeclimate.com/github/chippyash/Simple-Accounts)

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](https://github.com/chippyash/Simple-Accounts/blob/master/docs/Test-Contract.md)

### End of life notice
Expand All @@ -20,11 +26,13 @@ compatibility is not effort effective. See [PHP Version Stats](https://seld.be/

## What?

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

### Features

* Chart of Accounts \(see [here ](http://www.itzbits.co.uk/business-articles/67/What-is-a-Chart-of-Accounts.html) for a reasonable explanation\)
* Chart of Accounts \(see [here ](http://www.itzbits.co.uk/business-articles/67/What-is-a-Chart-of-Accounts.html)
for a reasonable explanation\)
* You can define your own chart structures
* Account types
* DR
Expand All @@ -43,18 +51,16 @@ Provides a simple double entry accounting system, that can be used as a componen
* Fantasy currencies are catered for
* Extensible Journal system, allowing recording of account transactions

The library is released under the [GNU GPL V3 or later license](http://www.gnu.org/copyleft/gpl.html)

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](http://www.amaranthgames.com/) 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.
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](http://www.amaranthgames.com/)
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

Expand Down Expand Up @@ -92,10 +98,11 @@ $chart = new Chart(new StringType('Foo Chart'), $org);
</pre>

##### 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.
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.

<pre>
use SAccounts\Accountant;
Expand All @@ -105,9 +112,9 @@ $fileClerk = new Serialized(new StringType('/path/To/My/Account/Store'));
$accountant = new Accountant($fileClerk);
</pre>

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.
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.

<pre>
use SAccounts\ChartDefinition;
Expand All @@ -122,14 +129,16 @@ $chart = $accountant->createChart(new StringType('Name of Chart'), $org, $def);
</pre>

#### 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.
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.
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

Expand All @@ -145,7 +154,7 @@ $chart->addAccount($ac)

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

#### Saving the chart
Expand All @@ -154,19 +163,24 @@ $accountant->fileChart($chart));
</pre>

#### Fetching the chart
In fetching a chart you need to know the id of the organisation that it belongs to

<pre>
$chart = $accountant->fetchChart(new StringType('Name of Chart'));
$chart = $accountant->fetchChart(new StringType('Name of Chart'), new IntType(1));
</pre>

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 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.
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.

<pre>
//can be used in most situations
Expand Down Expand Up @@ -214,16 +228,19 @@ The balance respects the conventions of DR and CR accounts.:

#### 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.
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.
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.

<pre>
use SAccounts\Storage\Journal\Xml as Journalist;
Expand All @@ -239,7 +256,8 @@ use Chippyash\Currency\Factory as Currency;
$journal = $accountant->createJournal(new StringType('My Journal'), Currency::create('gbp'));
</pre>

Under most circumstances, you'll associate an Organisation, and a Chart with a Journal, so it makes sense to use the same Currency:
Under most circumstances, you'll associate an Organisation, and a Chart with a Journal,
so it makes sense to use the same Currency:

<pre>
$journal = $accountant->createJournal(new StringType('My Journal'), $chart->getOrg()->getCurrency());
Expand All @@ -258,8 +276,9 @@ 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
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
Expand All @@ -281,8 +300,9 @@ You can set an optional 4th parameter when creating a SimpleTransaction:
$txn = new SimpleTransaction($drAc, $crAc, $amount, new StringType('This is a note'));
</pre>

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.
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.

<pre>
$txn = new SimpleTransaction($drAc, $crAc, $amount, new StringType(''), new \DateTime('2015-12-03T12:14:30Z));
Expand All @@ -302,14 +322,14 @@ The Transaction will now have its transaction id set, which you can recover via:
$txnId = $txn->getId() //returns IntType
</pre>

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!
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. valid double entry transaction.
amounts, you have a balanced transaction, i.e. a valid double entry transaction.

With power comes a little more complexity, as you'd expect!

Expand Down Expand Up @@ -456,7 +476,7 @@ Install [Composer](https://getcomposer.org/)
#### For production

<pre>
"chippyash/simple-accounts": "~1"
"chippyash/simple-accounts": "~2"
</pre>

#### For development
Expand All @@ -478,19 +498,21 @@ To run the tests:

## 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](https://github.com/sebastianbergmann/phpunit)
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](https://github.com/sebastianbergmann/phpunit)
and [vfsStream](https://github.com/mikey179/vfsStream) for writing the test code,
I'd like to highlight some others:

* [PHP Enum](https://github.com/myclabs/php-enum) : a neat implementation of enums for PHP
* [Tree](https://github.com/nicmart/Tree) : A simple tree component that supports the visitor pattern allowing for easy extension
* [Tree](https://github.com/nicmart/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](http://www.gnu.org/copyleft/gpl.html)

This software library is Copyright (c) 2015-2016, Ashley Kitson, UK
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
Expand Down Expand Up @@ -523,4 +545,6 @@ V1.4.4 Dependency update

V1.4.5 PhpUnit test suite update

V1.4.6 Update build script
V1.4.6 Update build script

V2.0.0 BC break in some interface definitions to support implementation of DB based systems.
2 changes: 2 additions & 0 deletions composer.json
View file
Expand Up @@ -19,6 +19,8 @@
"chippyash/currency": ">=3,<4",
"chippyash/monad": ">=1,<2",
"chippyash/assembly-builder": ">=1,<2",
"chippyash/identity": ">=1.0.2,<2",
"chippyash/record-status": ">=1.0.0,<2",
"myclabs/php-enum": ">=1.3.2,<2",
"nicmart/tree": ">=0.2.5,<1"
},
Expand Down

0 comments on commit 30918b6

Please sign in to comment.