PHP Classes

Nest: Easily set and get values of nested arrays

Recommend this page to a friend!
  Info   View files Documentation   View files View files (27)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
Not enough user ratingsTotal: 178 This week: 1All time: 8,733 This week: 560Up
Version License PHP version Categories
nest 1.2.3GNU General Publi...5.4PHP 5, Data types, Language
Description 

Author

This class can easily set and get values of nested arrays.

It extends the ArrayObject class to be able to get or set the values of nested array entries with one access to a single variable.

The variable must be named with the indexes of the nested array for each dimension separated with a special sequence of characters which defaults to __ .

When getting an array value with indexes that are not set, the class may return null or a given a default value.

The class also provides functions to perform other functions like incrementing and decrementing array values, appending new values, sorting the array, merging new values, export and import the array from a string in JSON format, etc..

Picture of Rick Hambrook
  Performance   Level  
Name: Rick Hambrook <contact>
Classes: 1 package by
Country: New Zealand New Zealand
Age: ???
All time rank: 421018 in New Zealand New Zealand
Week rank: 416 Up4 in New Zealand New Zealand Up

Documentation

Nest

By Rick Hambrook

Build Status

Nest is a PHP class that lets you easily get and set values in nested arrays and objects without worrying about errors or missing data. You don't have to check if keys, properties or functions exist. It's all designed to fail gracefully.

Need a value from an array that is returned by a function that requires parameters on an object which is stored in an array? Nest will get it for you, or return a default value if the one you want isn't there. Easy.

You can get and set nested values. You can iterate over them with foreach. The only limitation is that you can't set the value returned by a function because, well, it's obvious.

Why do this...

// need to get $array["one"]["two"]
if (array_key_exists("one", $array) && array_key_exists("two", $array["one"])) {
	$value = $array["one"]["two"];
}

When you could do this?

// need to get $array["one"]["two"]
$value = $array->one__two;

You don't have to worry about any key checks, or checking if things are set... Just fetch the value. You can specify a default value (null by default) to use in case the one you want isn't there. Focus on building great apps instead of validating data.

Example

$Nest = new \Hambrook\Nest\Nest(
	[
		"foo" => "bar",
		"one" => [
			"two" => "three"
		]
	]
);

Use a string as the path parameter

$value = $Nest->get("foo");
// "bar"

We're going two levels in this time, so use an array for the path

$value = $Nest->get(["one", "two"]);
// "three"

What if we try to get something that isn't there? Does it error?

$value = $Nest->get(["nope", "two"]);
// returns `null`, not an error

Or we can specify our own default in case of error

$value = $Nest->get(["nope", "two"], "safe");
// returns "safe", not an error

Who is it for?

Nest is for working with arrays and objects were you aren't always sure of the data. It works great with the Config class for storing configuration data for other classes or CLI scripts. But it can be used anywhere.

Where are the exceptions?

Nest doesn't throw any exceptions, that's the rule. Nest was designed to fail gracefully with default values instead of using exceptions.

What about the performance hit?

Although Nest can be used anywhere, it was built primarily for CLI apps where milliseconds don't matter. I've kept speed in mind but it's not a primary concern. At some point I will add benchmarks and timing and see how much I can shave off the execution time.

Testing

Install PHPUnit globally, then run it on the tests/ directory.

Feedback

Tell me if you loved it. Tell me if you hated it. Tell me if you used it and thought "meh". I'm keen to hear your feedback.

Contributing

Feel free to fork this project and submit pull requests, or even just request features via the issue tracker. Please be descriptive with pull requests and match the existing code style.

Roadmap

  • PHP7 support
  • Add any other standard documentation that should be included
  • Maybe add a parameter to get() that allows specifying a validator callback
  • _If you have an idea, let me know._

License

Copyright &copy; 2015 Rick Hambrook

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.


  Files folder image Files  
File Role Description
Files folder imagesrc (1 file)
Files folder imagedocs (1 file)
Files folder imagetests (19 files)
Accessible without login Plain text file .travis.yml Data Auxiliary data
Accessible without login Plain text file CHANGELOG Data Changelog
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file COPYRIGHT Lic. Copyright information
Accessible without login Plain text file LICENSE Lic. License information
Accessible without login Plain text file README.md Doc. ReadMe

  Files folder image Files  /  src  
File Role Description
  Plain text file Nest.php Class Nest class

  Files folder image Files  /  docs  
File Role Description
  Accessible without login Plain text file Docs.md Doc. Full docs

  Files folder image Files  /  tests  
File Role Description
  Accessible without login Plain text file arrayForeachTest.php Test Unit test: array foreach
  Accessible without login Plain text file arrayGetTest.php Test Unit test: array get
  Accessible without login Plain text file arrayHelpersTest.php Test Unit test: array helpers
  Accessible without login Plain text file arrayIsSetTest.php Test Unit test: is set
  Accessible without login Plain text file arrayMathTest.php Test Unit test: array math
  Accessible without login Plain text file arraySetTest.php Test Unit test: array set
  Accessible without login Plain text file arrayStaticTest.php Test Unit test: array static
  Accessible without login Plain text file dataTest.php Test Unit test: data
  Accessible without login Plain text file issetTest.php Test Unit test: is set
  Accessible without login Plain text file jsonTest.php Test Unit test: json
  Accessible without login Plain text file magicPrefixTest.php Test Unit test: magic prefix
  Accessible without login Plain text file objectForeachTest.php Test Unit test: object foreach
  Accessible without login Plain text file objectGetFunctionsTest.php Test Unit test: object get functions
  Accessible without login Plain text file objectGetPropertiesTest.php Test Unit test: object get properties
  Accessible without login Plain text file objectSetTest.php Test Unit test: object set
  Accessible without login Plain text file objectStaticTest.php Test Unit test: object static
  Accessible without login Plain text file serializeTest.php Test Unit test: serialize
  Accessible without login Plain text file sortTest.php Test Unit test: sort
  Accessible without login Plain text file unsetTest.php Test Unit test: unset

 Version Control Unique User Downloads Download Rankings  
 100%
Total:178
This week:1
All time:8,733
This week:560Up