Download the PHP package girover/tree without Composer

Building Family Tree

Content

• Introduction
• prerequisites
• Installation
• Assets
• Images
• Usage
  • Treeable Model
  • Pointer
  • Nodeable Model
    • Retrieving nodes
    • Adding nodes
    • Deleting nodes
    • Checking nodes
    • Relationships
    • Relocating nodes
    • Attaching and Detaching nodes
  • Helpers
  • Rendering Trees
  • Customizing node style
• Testing
• Changelog
• Contributing
• Security Vulnerabilities
• Credits
• License

Introduction

girover/laravel-family-tree is a package that allows you to build family trees. With this package it will be very simple to create trees and add nodes to trees.

Every tree is allowed to have 85 generations. Assuming each generation has 20 years, this means that 1700 years of data can be stored in one tree.
Every node in a tree is allowed to have 676 direct children.

prerequisites

• Laravel 8+
• PHP 8+
• Mysql 5.7+

Installation

You can add the package via composer:

Before installing the package you should configure your database.

Then you can install the package by running Artisan command

this command will take care of the following tasks:

• Publishing Config file to the config folder of your Laravel application.
• Publishing migration files to folder in your application.
• Migrate the published migrations.
• Publishing Assets (css, js, images) to the public folder in your application and they will be placed in .
• Publishing JSON Translation files to the

  Assets

After publishing assets (css, js, images), they will be placed in public folder of the project in a folder called vendor/tree. You are free to move any of these assets to other directories.

You should add the CSS file to your blade file to get the tree styled.

Images

Every node in tree has an avatar photo. Male and Female Icons by default will be stored in the public folder under
.
however you are free to choose another folder for the images of nodes, but you must provide it in the file.

So your images folder should be in the **** folder. Example: if images are stored in folder called the configs must be:

Note: When saving photos in storage folder, it is important to create symbolic link to the photos folder.

Usage

To start building family trees, you must have two models. The first one represents trees in database and it must use the trait:

The second model represents nodes in these trees, and it must use trait:

NOTE: The names of the models that represents trees and nodes in database must be provided in .

Treeable Model

To start building a tree or creating a new tree, it is very simple and thanks to Eloquent models from Laravel.
The model that represents trees in database should use trait: For example if your model is called so it should looks like this:

And now you can use your model to deal with trees.

After creating the tree, you can start to add as many nodes as you want.
Let's start adding the First node, the ****, to the tree.

What if you want to make a new Root?
In this case you can use the method ****, and the previously created Root will become a child of the new created Root.

After creating the Root in the tree, let's add first child for the Root.

Now our tree consists of two nodes, the root and the first child of the root.

Pointer

A tree has a Pointer inside it, and this Pointer points to one node.
Pointer can move through all nodes in the tree.
Because the Pointer points to a node inside the tree, so it can call all methods of model that uses Nodeable Trait .
To get the pointer you can do the following:

And now you can use the pointer to make a lot of actions inside the tree, for example moving through nodes, deleting and retrieving more information about nodes.
Eg. To move the pointer to specific node:

And now you can get the node data by calling the method

Note that we called method after we had called the method .
This is because when a tree object is created, its Pointer indicates to .

Nodeable Model

• What is a node
• Retrieving nodes
• Adding nodes
• Deleting nodes
• Checking nodes
• Relationships
• Relocating nodes
• Attaching and Detaching nodes

What is a node

Node is a person in a tree and every node in the tree is connected with another one by using Location mechanism.

To retrieve a nodes you can use Eloquent model that uses trait

Retrieving nodes

To get the tree that the node belongs to.

To get the father of the node:

To get the grandfather of the node:

To get the ancestor that matches the given number as parameter.

To get all ancestors of a node

To get all uncles of the node:

To get all aunts of the node:

To get all children of the node:

To get all sons of the node:

To get all daughters of the node:

To get all descendants of the node:

To get all male descendants of the node:

To get all female descendants of the node:

To get the first child of the node:

To get the last child of the node:

To get all siblings of the node:

To get all brothers of the node:

To get all sisters of the node:

To get the next sibling of the node. gets only one sibling.

To get all the next siblings of the node. siblings who are younger.

To get the next brother of the node. gets only one brother.

To get all the next brothers of the node. brothers who are younger.

To get the next sister of the node. gets only one sister.

To get all the next sisters of the node. sisters who are younger.

To get the previous sibling of the node. only one sibling.

To get all the previous siblings of the node. siblings who are older.

To get the previous brother of the node. only one brother.

To get all the previous brothers of the node. brothers who are older.

To get the previous sister of the node. only one sister.

To get all the previous sisters of the node. sisters who are older.

To get the first sibling of the node.

To get the last sibling of the node.

To get the first brother of the node.

To get the last brother of the node.

To get the first sister of the node.

To get the last sister of the node.

Adding nodes

The next code will create father for a node, only if this node is a Root in the tree.
If the node is not a , will be thrown.

To create new sibling for the node:

To create new brother for the node:

To create new sister for the node:

To create new son for the node:

To create new daughter for the node:

To make the node as the main node in its tree.

Deleting nodes

To delete a node.

note: The node will be deleted with all its descendants.
But if you want just to delete the node and not its descendants,
then you can move its descendants before deleting the node.

Or you can directly move children to the father of deleted node by using method without passing any node as parameter.

To delete all children of a node:

Checking nodes

To determine if the node is root in the tree

To determine if the node is ancestor of another node:

To determine if the node is father of another node:

Determine if the node has children

To determine if the node is child of another node:

Determine if the node has siblings

To determine if the node is sibling of another node:

To count the children of the node:

To count sons of a node:

To count daughters of the node:

To count all siblings of the node:

To count all brothers of the node:

To count all sisters of the node:

To count all descendants of the node:

To count all male descendants of the node:

To count all female descendants of the node:

Relationships

To get all wives of the node:

When trying to get wives of female node a will be thrown.
Note that this will get divorced wives too.
To get only wives who are not divorced you can do this:

To get husbands of the node:

When trying to get husband of male node a will be thrown.
Note that this will get divorced husbands too.
To get only husbands who are not divorced you can do this:

To assign wife to a node:

When trying to do this with a female node (woman) a will be thrown. so if is a woman Exception will be thrown.

To divorce a wife

When trying to do this with a female node a will be thrown. so if is a woman Exception will be thrown.

To set uploaded photo to the node:

Relocating nodes

to move an existing node to be child of another node.
Note this will move the node with its children.

To move children of a node to be children of another node
you can do this:

Note: When trying to move node1 to node2, if node2 is descendant of node1 will be thrown.
The same exception will be thrown if node2 is a female node.

To move a node after another node you can do this:

To move a node before another node you can do this:

Note: When trying to move the Root or when trying to move a node after or before one of its descendants will be thrown.

to get the generation number of a node in a tree:

Note: You can use the Pointer of tree to access all methods of class Node.
for example:

Attaching and Detaching

When creating nodeable models by using methods or , the created model will not be attached with any node in any tree.

Both $person and $another_person will be created in database table, but they will not be a node yet in any tree.
To make Adam as a node in a tree you can use all nodeable methods like:

detaching

When deleting nodeable models they will be deleted from database table, but what if you need to delete(detach) them from a tree while keeping them in database.
Let's look at the following code:

In the code above, the person will be deleted from database with all its descendants.

But we need only to delete it from a tree not from database. Look at this code:

Now the person still exists in database, but it is not a node in any tree anymore.

Helpers

To get all detached nodeable models, you can use the helper function .
This will return instance of with all detached nodeable models.

To get the count of detached nodeable models, use the helper function .

Rendering trees

To show a tree in the browser you can use one of these methods , or on an object of the Treeable model eg.

And now inside your blade file you can render the tree by using custom blade directive or by using this syntax .

Note the above example will render the entire tree, but if you want to render a subtree starting from a specific node you can use the Pinter to do that:

You can also use a node model to do the same by using one of these methods , or on an object of the nodeable model eg. :

Customizing node style

If you want to add some html attributes to the nodes, then you can bind a custom function called to the Service Container. This function must return a callable function which accept one argument represents nodeable model. And this callable function must return html attributes with their values as one string.
Let's take an example.
If your nodeable models have fields , then you want to add them as html attributes to the nodes to style or to control nodes.

Now all node elements will have these attributes like:

If you want to add some css classes to the nodes that have specific role, then you can bind a custom function called to the Service Container. This function must return a callable function which accept one argument represents nodeable model. And this callable function must return css classes names as string.
Let's take an example.
If your nodeable models have an attribute called which has values or , then you want to add a css class called to the nodes that have this value as to give them more style.

Now all nodeables that have to true will be like:

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Majed Girover
• All Contributors

License

The MIT License (MIT). Please see License File for more information.