<commit_before># MPTT

MPTT is a simple implementation of MPTT (Modified Preorder Tree Traversal). It provides ways to create, move, and delete tree nodes in a database table, and has a few utility methods.

# Installation

Before using MPTT, you have to make sure to have certain modules installed and a properly configured database table.

## Module Dependencies

 - Kohana database

## Module Initialization

Initialize the kohana database module and XMPTT in application/bootstrap.php.

## Database Configuration

Make sure you configure kohana's database module properly so that you can connect and use the database you wish to perform MPTT operations on.

## Database Table Requirements

To use XMPTT with a database table, the table requires the following columns:

 - id (int) - a unique id
 - lft (int) - a node's left value
 - rgt (int) - a node's right value
 - depth (int) - a node's depth
 
If you wish to use scopes, you must also add this column:
 
 - scope (int) - a node's scope
 
You can add as many other columns as you want.

# Usage

XMPTT is used to perform MPTT operations on a desired database table. Before continuing, make sure your modules and database are installed and configured properly.

## Initialization

	// Use the pages table.
	$mptt = new MPTT('pages');

	// Use the pages table with a scope of 1.
	$mptt = new MPTT('pages', 1);

## Modify the table and the scope

	// Change the table and scope.
	$mptt->table = 'categories';
	$mptt->scope = 2;

	// Remove the use of a scope.
	$mptt->scope = NULL;

## Insert a node

	$data = array('name' => 'joe', 'active' => '1');
	$mptt->insert($data);

## Move a node and its children

Two relationships are supported for the moving of nodes:

 + after
 + first child of

These two relationships permit all the possible types of allowed movements. There are a few illegal movements that will genarate an exception:

 + If you try to move a node unto itself.
 + If you try to move the root.
 + If you try to make a parent become the child of its own child.

~~~~
	// Move node id 4 after node id 5
	$moved = $mptt->move(4, 'after', 5);

	// Move node id 5 to make it the first child of node id 6
	$moved = $mptt->move(5, 'first child of', 6);
~~~~

## Delete node(s)

To delete a node or nodes, you simply pass a node id, or an array of node ids to the delete method. If the node has children, they will be deleted automatically.

If you attempt to delete the root id, it will be silently ignored. If you delete every node except the root id, the root id will automatically be deleted as well.

	// Delete the node with an id of 2.
	$deleted = $mptt->delete(2);

	// Delete nodes with ids of 2 and 3.
	$deleted = $mptt->delete(array(2, 3));

## Transactions (insert, move, delete)

XMPTT does not create transactions automatically, but it does indicate whether an operation has succeeded or failed. At the end of an insert, move, or delete operation, the tree is checked to make sure its construction is still valid. If the check fails, the method will return a value of FALSE.

An operation should never fail unless there is a database problem. If an operation does fail, this means the tree's construction might no longer be valid. For this reason, it is crucial that you create a transaction for every insert, move, and delete command you perform on the tree.

Transactions were not direcly included in XMPTT to allow the ability to perform other queries in addition to your XMPTT queries. Since MYSQL does not permit nested transactions, this was the most flexible option.

	// Start the transaction.
	DB::query(NULL, "BEGIN WORK")->execute();

	// You can make other queries here.

	$deleted = $mptt->delete(array(3, 4));

	if ($deleted !== FALSE)
	{

		// You can make other queries here.

		// Commit the transaction.
		DB::query(NULL, "COMMIT")->execute();
	}

For the insert and move method you can simply check for a FALSE value like so; `$inserted != FALSE`. This does not work for the deleted method because it will return an empty array if no deletions have been made. In such a case, the tree will remain valid and the operation can still be considered successful. You must thus use `$deleted !== FALSE` to know if a deletion was truly successful.
<commit_msg>added installation instructions to README.md<commit_after># MPTT

## About

MPTT is a simple MPTT (Modified Preorder Tree Traversal) implementation for Kohana 3.3.0, a PHP framework. It provides ways to create, move, and delete tree nodes in a database table, and has a few utility methods.

## Documentation

The documentation on this page is also contained in the guide folder. You can view it using Kohana's userguide.

## Installation

Before using MPTT, you need to activate and configure Kohana's database module, and create a database table to perform MPTT operations on.

## Module Dependencies

 - Kohana database

## Module Activation

Activate Kohana's database module and the MPTT module in application/bootstrap.php.

## Database Configuration

Make sure you properly configure Kohana's database module in order to connect and use the database you wish to perform MPTT operations on.

## Database Table Requirements

To use MPTT, you need a database table with the following columns:

 - id (int) - a unique id
 - lft (int) - a node's left value
 - rgt (int) - a node's right value

If you wish to use scopes, you must also add this column:

 - scope (int) - a node's scope

You can add as many other columns as you wish depending on your intended use of MPTT.

## Example Table

A table of categories using scopes with a product count for each category:

 - id (int) - a unique id
 - lft (int) - a node's left value
 - rgt (int) - a node's right value
 - scope (int) - a node's scope
 - category (string) - the category's name
 - num_products (int) - the number of products in the category

{'fraction_non_alphanumeric': 0.07139197267292913, 'fraction_numerical': 0.003928266438941076, 'mean_word_length': 3.707395498392283, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 16, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1101527', 'n_tokens_mistral': 1656, 'n_tokens_neox': 1555, 'n_words': 908}