README

Quality Assurance

See the Test Contract

What?

Provides a simple helper capability for managing record or class status

Why?

When dealing with database records, there is often a case for never deleting the record. This can be because you either don't want to lose the data, or you need it in place to ensure referential integrity with other data.

This small library provides the interfaces and traits to add a status functionality to any class.

Roadmap

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

A record can be in one of three states:

• active. An active record can have be changed to suspended or defunct
• suspended. A suspended record can be changed to active of defunct. You should not change the attributes of a suspended reord.
• defunct. A defunct record or class cannot have its state changed. This analogous to being deleted, except that the record data remains intact. You must not change the attributes of a defunct record.

Whilst the library provides support to manage the record status, you should also bear in mind that you will need to provide additional support to check the status in any of your other methods in a class.

In the docs directory, you'll also find an example trigger that you can use in MySql or MariaDb database server to maintain status integrity.

Coding Basics

Record Status Enum class

The Chippyash\RStatus\RecordStatus class is provided to provide the three possible states as a an Enum(erator) using the MyCLabs Enum library.

use Chippyash\RStatus\RecordStatus;

//create status objects
$status = RecordStatus::ACTIVE();
$status = RecordStatus::SUSPENDED();
$status = RecordStatus::DEFUNCT();

//test if status can be changed
if ($status->canChange()) {
	//....
}

Enabling RecordStatus for your class

Have your class implement the RecordStatusRecordable interface. Use the RecordStatusRecording trait as a convenient implementation of the interface.

use Chippyash\RStatus\RecordStatusRecordable;
use Chippyash\RStatus\RecordStatusRecording;

class MyRecord implements RecordStatusRecordable
{
	use RecordStatusRecording;
}

The RecordStatusRecording trait provides a protected $recordStatus propertyand the following methods:

/**
 * Return the record status
 *
 * @return RecordStatus
 */
public function getStatus();

/**
 * Set the record status
 *
 * @param RecordStatus $status
 *
 * @return $this
 *
 * @throws RecordStatusException
 */
public function setStatus(RecordStatus $status);

/**
 * Is record status == active
 *
 * @return bool
 */
public function isStatusActive();

/**
 * Is record status == suspended
 *
 * @return bool
 */
public function isStatusSuspended();

/**
 * Is record status == defunct
 *
 * @return bool
 */
public function isStatusDefunct();

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/record-status": ">=1,<2"

For development

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

    git clone git@github.com:chippyash/record-status.git
    cd record-status
    composer install

To run the tests:

    cd record-status
    vendor/bin/phpunit -c test/phpunit.xml test/

License

This software library is released under the GNU GPL V3 or later license

This software library is Copyright (c) 2017, 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.0.1 build integration

V1.0.2 typos