Download the PHP package poing/earmark without Composer
On this page you can find all versions of the php package poing/earmark. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download poing/earmark
More information about poing/earmark
Files in poing/earmark
Package earmark
Short Description Laravel package to generate values in a unique and customizable series.
License MIT
Homepage https://github.com/poing/earmark
Informations about the package earmark
Earmark
A Laravel package to earmark sequential values in a series and eliminate any gaps in the series when values are unset
. Allowing for values to be reused.
It can be used to fetch the next value (or array of values) to be used in an application. Database locking is used to prevent duplicate values from being returned.
An example...
Reserving the next available phone extension for a user. The phone extension can be reserved by the active session, preventing other sessions from obtaining the same value.
When a user leaves the phone extension can be recycled, the value can be unset()
. Making the value available again for a future request.
Getting Started
1. Install EarMark
Run this at the command line:
This will update composer.json and install the package into the vendor/ directory.
2. Publish the EarMark Configuration File
To over-ride the default settings, initialize the config file by running this command:
Then open config/earmark.php and edit the settings to meet the requirements of your application.
3. Run the Migrations
Run the package migration files at the command line:
4. Recommended
This package is designed to use Laravel Queues, to defer the time consuming task of repopulating the available pool of values.
You may want to change the default QUEUE_CONNECTION
to use another strategy. But the package also works with the default sync
, but may cause latency in your application.
Settings
Hold Size
This is the number of series values that are kept in an available pool. Once the pool drops below a certain level, more values are added to the pool. This is where unused values are recycled.
Important:
- Replenishing the hold will be time consuming and may take minutes to complete.
- Depending on how you use Earmark, the hold size should be a multiple of the maximum
get()
requests expected. - Hold size should be configured to allow for a sufficient number of
get()
requests after falling below one-third.
Number Range
This package currently supports a minimal value. range.min
will define the starting value of the series. Default: 2000
range.max
may be used in the future.
Zero Padding
Allows the output value to be zero-padded, depending on the needs of the application.
Prefix & Suffix
Appends a prefix to the output value.
suffix
may be used in the future.
How to Use
There are two ways to use this package:
Earmarked
to use the default values in the pool. The default values are already "Earmarked".Earmark
to create a new pool of values to use. Use custom settings with a new "Earmark".
Available Functions:
get()
- Returns a single formated value.
- Will accept option integer to return an array of formatted values.
unset($value)
- Accepts formated values as a string or array.
Simple Usage
With the values from the configuration file, use Earmarked::get()
and Earmarked::unset()
.
You can also specify the number of values to return in an array:
Advanced Usage
You can initialize a new series using Earmark()
and supplying the following variables:
- prefix
- suffix (non-functional placeholder)
- padding
- min
- max (non-functional placeholder)
The new series will not affect the default series, calling the series again (with the same parameters) will continue the numeric series.
How it works
Searching for gaps in a numerical series of numbers can be resource intensive. Depends on the size of the series.
This package uses two (2
) tables, one for the series of used numbers and one to Hold
a group of available numbers for immediate use. The package will get()
the next consecutive number from the Hold
table.
When the available numbers in the Hold
table falls below one-third, this package will repopulate the Hold
with more numbers. This package works best with Laravel queues.
Numbers in a series that have been unset()
will be added to the Hold
table for reuse when updated. Numbers in the Hold
table are not sorted, unset()
numbers will eventually be available again.
Additional Feature
Auto-Increment
Sometimes you just want the next number in an auto-increment series. One is included in this package. It does not support prefix
, will not support suffix
, but you can use zero-padding.
Do not use unset()
with increment()
values! You have been warned!
Contributing
Thinking of contributing?
- Fork & clone the project:
git clone [email protected]:your-username/earmark.git
. - Run the tests and make sure that they pass with your setup:
phpunit
. - Create your bugfix/feature branch and code away your changes. Add tests for your changes.
- Make sure all the tests still pass:
phpunit
. - Push to your fork and submit new a pull request.
All versions of earmark with dependencies
illuminate/console Version >=11.0
illuminate/database Version >=11.0
illuminate/events Version >=11.0
illuminate/filesystem Version >=11.0
illuminate/support Version >=11.0