Download the PHP package ngoubaux/etrepat-baum without Composer

On this page you can find all versions of the php package ngoubaux/etrepat-baum. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package etrepat-baum

Baum

Build Status

Baum is an implementation of the Nested Set pattern for Laravel 5's Eloquent ORM.

For Laravel 4.2.x compatibility, check the 1.0.x branch branch or use the latest 1.0.x tagged release.

Documentation

About Nested Sets

A nested set is a smart way to implement an ordered tree that allows for fast, non-recursive queries. For example, you can fetch all descendants of a node in a single query, no matter how deep the tree. The drawback is that insertions/moves/deletes require complex SQL, but that is handled behind the curtains by this package!

Nested sets are appropriate for ordered trees (e.g. menus, commercial categories) and big trees that must be queried efficiently (e.g. threaded posts).

See the wikipedia entry for nested sets for more info. Also, this is a good introductory tutorial: http://www.evanpetersen.com/item/nested-sets.html

The theory behind, a TL;DR version

An easy way to visualize how a nested set works is to think of a parent entity surrounding all of its children, and its parent surrounding it, etc. So this tree:

root
  |_ Child 1
    |_ Child 1.1
    |_ Child 1.2
  |_ Child 2
    |_ Child 2.1
    |_ Child 2.2

Could be visualized like this:

 ___________________________________________________________________
|  Root                                                             |
|    ____________________________    ____________________________   |
|   |  Child 1                  |   |  Child 2                  |   |
|   |   __________   _________  |   |   __________   _________  |   |
|   |  |  C 1.1  |  |  C 1.2 |  |   |  |  C 2.1  |  |  C 2.2 |  |   |
1   2  3_________4  5________6  7   8  9_________10 11_______12 13  14
|   |___________________________|   |___________________________|   |
|___________________________________________________________________|

The numbers represent the left and right boundaries. The table then might look like this:

id | parent_id | lft  | rgt  | depth | data
 1 |           |    1 |   14 |     0 | root
 2 |         1 |    2 |    7 |     1 | Child 1
 3 |         2 |    3 |    4 |     2 | Child 1.1
 4 |         2 |    5 |    6 |     2 | Child 1.2
 5 |         1 |    8 |   13 |     1 | Child 2
 6 |         5 |    9 |   10 |     2 | Child 2.1
 7 |         5 |   11 |   12 |     2 | Child 2.2

To get all children of a parent node, you

To get the number of children, it's

To get a node and all its ancestors going back to the root, you

As you can see, queries that would be recursive and prohibitively slow on ordinary trees are suddenly quite fast. Nifty, isn't it?

Installation

Baum works with Laravel 5 onwards. You can add it to your composer.json file with:

"baum/baum": "~1.1"

Run composer install to install it.

As with most Laravel 5 packages you'll then need to register the Baum service provider. To do that, head over your config/app.php file and add the following line into the providers array:

'Baum\Providers\BaumServiceProvider',

Getting started

After the package is correctly installed the easiest way to get started is to run the provided generator:

php artisan baum:install MODEL

Replace model by the class name you plan to use for your Nested Set model.

The generator will install a migration and a model file into your application configured to work with the Nested Set behaviour provided by Baum. You SHOULD take a look at those files, as each of them describes how they can be customized.

Next, you would probably run artisan migrate to apply the migration.

Model configuration

In order to work with Baum, you must ensure that your model class extends Baum\Node.

This is the easiest it can get:

This is a slightly more complex example where we have the column names customized:

Remember that, obviously, the column names must match those in the database table.

Migration configuration

You must ensure that the database table that supports your Baum models has the following columns:

Here is a sample migration file:

You may freely modify the column names, provided you change them both in the migration and the model.

Usage

After you've configured your model and run the migration, you are now ready to use Baum with your model. Below are some examples.

Creating a root node

By default, all nodes are created as roots:

Alternatively, you may find yourself in the need of converting an existing node into a root node:

You may also nullify it's parent_id column to accomplish the same behaviour:

Inserting nodes

Deleting nodes

Descendants of deleted nodes will also be deleted and all the lft and rgt bound will be recalculated. Pleases note that, for now, deleting and deleted model events for the descendants will not be fired.

Getting the nesting level of a node

The getLevel() method will return current nesting level, or depth, of a node.

Moving nodes around

Baum provides several methods for moving nodes around:

For example:

Asking questions to your nodes

You can ask some questions to your Baum nodes:

Using the nodes from the previous example:

Relations

Baum provides two self-referential Eloquent relations for your nodes: parent and children.

Root and Leaf scopes

Baum provides some very basic query scopes for accessing the root and leaf nodes:

You may also be interested in only the first root:

Accessing the ancestry/descendancy chain

There are several methods which Baum offers to access the ancestry/descendancy chain of a node in the Nested Set tree. The main thing to keep in mind is that they are provided in two ways:

First as query scopes, returning an Illuminate\Database\Eloquent\Builder instance to continue to query further. To get actual results from these, remember to call get() or first().

Second, as methods which return actual Baum\Node instances (inside a Collection object where appropiate):

Here's a simple example for iterating a node's descendants (provided a name attribute is available):

Limiting the levels of children returned

In some situations where the hierarchy depth is huge it might be desirable to limit the number of levels of children returned (depth). You can do this in Baum by using the limitDepth query scope.

The following snippet will get the current node's descendants up to a maximum of 5 depth levels below it:

Similarly, you can limit the descendancy levels with both the getDescendants and getDescendantsAndSelf methods by supplying the desired depth limit as the first argument:

Custom sorting column

By default in Baum all results are returned sorted by the lft index column value for consistency.

If you wish to change this default behaviour you need to specify in your model the name of the column you wish to use to sort your results like this:

Dumping the hierarchy tree

Baum extends the default Eloquent\Collection class and provides the toHierarchy method to it which returns a nested collection representing the queried tree.

Retrieving a complete tree hierarchy into a regular Collection object with its children properly nested is as simple as:

Model events: moving and moved

Baum models fire the following events: moving and moved every time a node is moved around the Nested Set tree. This allows you to hook into those points in the node movement process. As with normal Eloquent model events, if false is returned from the moving event, the movement operation will be cancelled.

The recommended way to hook into those events is by using the model's boot method:

Scope support

Baum provides a simple method to provide Nested Set "scoping" which restricts what we consider part of a nested set tree. This should allow for multiple nested set trees in the same database table.

To make use of the scoping funcionality you may override the scoped model attribute in your subclass. This attribute should contain an array of the column names (database fields) which shall be used to restrict Nested Set queries:

In the previous example, company_id effectively restricts (or "scopes") a Nested Set tree. So, for each value of that field we may be able to construct a full different tree.

All methods which ask or traverse the Nested Set tree will use the scoped attribute (if provided).

Please note that, for now, moving nodes between scopes is not supported.

Validation

The ::isValidNestedSet() static method allows you to check if your underlying tree structure is correct. It mainly checks for these 3 things:

All of the checks are scope aware and will check each scope separately if needed.

Example usage, given a Category node class:

Tree rebuilding

Baum supports for complete tree-structure rebuilding (or reindexing) via the ::rebuild() static method.

This method will re-index all your lft, rgt and depth column values, inspecting your tree only from the parent <-> children relation standpoint. Which means that you only need a correctly filled parent_id column and Baum will try its best to recompute the rest.

This can prove quite useful when something has gone horribly wrong with the index values or it may come quite handy when converting from another implementation (which would probably have a parent_id column).

This operation is also scope aware and will rebuild all of the scopes separately if they are defined.

Simple example usage, given a Category node class:

Valid trees (per the isValidNestedSet method) will not get rebuilt. To force the index rebuilding process simply call the rebuild method with true as the first parameter:

Soft deletes

Baum comes with limited support for soft-delete operations. What I mean by limited is that the testing is still limited and the soft delete functionality is changing in the upcoming 4.2 version of the framework, so use this feature wisely.

For now, you may consider a safe restore() operation to be one of:

Seeding/Mass-assignment

Because Nested Set structures usually involve a number of method calls to build a hierarchy structure (which result in several database queries), Baum provides two convenient methods which will map the supplied array of node attributes and create a hierarchy tree from them:

Both methods will create new nodes when the primary key is not supplied, update or create if it is, and delete all nodes which are not present in the affecting scope. Understand that the affecting scope for the buildTree static method is the whole nested set tree and for the makeTree instance method are all of the current node's descendants.

For example, imagine we wanted to map the following category hierarchy into our database:

This could be easily accomplished with the following code:

After that, we may just update the hierarchy as needed:

The makeTree instance method works in a similar fashion. The only difference is that it will only perform operations on the descendants of the calling node instance.

So now imagine we already have the following hierarchy in the database:

If we execute the following code:

Would result in:

Updating and deleting nodes from the subtree works the same way.

Misc/Utility functions

Node extraction query scopes

Baum provides some query scopes which may be used to extract (remove) selected nodes from the current results set.

Get a nested list of column values

The ::getNestedList() static method returns a key-value pair array indicating a node's depth. Useful for silling select elements, etc.

It expects the column name to return, and optionally: the column to use for array keys (will use id if none supplied) and/or a separator:

An example use case:

Further information

You may find additional information, usage examples and/or frequently asked questions about Baum in the wiki.

Feel free to browse the wiki after finishing this README:

https://github.com/etrepat/baum/wiki

Contributing

Thinking of contributing? Maybe you've found some nasty bug? That's great news!

  1. Fork & clone the project: git clone [email protected]:your-username/baum.git.
  2. Run the tests and make sure that they pass with your setup: phpunit.
  3. Create your bugfix/feature branch and code away your changes. Add tests for your changes.
  4. Make sure all the tests still pass: phpunit.
  5. Push to your fork and submit new a pull request.

Please see the CONTRIBUTING.md file for extended guidelines and/or recommendations.

License

Baum is licensed under the terms of the MIT License (See LICENSE file for details).


Coded by Estanislau Trepat (etrepat). I'm also @etrepat on twitter.


All versions of etrepat-baum with dependencies

PHP Build Version
Package Version
Requires php Version ^8.0
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
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package ngoubaux/etrepat-baum contains the following files

Loading the files please wait ....