A Star pathfinding algorithm implementation for PHP.
-
Install composer.
-
Add the A Star algorithm package to your
composer.json
file:"require": { ... "jmgq/a-star": "1.*" ... }
-
Update composer:
composer update
-
Create a class that implements the
Node
interface. The easiest option is to create a class that extendsAbstractNode
. It requires to implement thegetID
method:use JMGQ\AStar\AbstractNode; class MyNode extends AbstractNode { // ... public function getID() { // Return a unique identifier for this node } // ... }
-
Extend the
AStar
class, which requires to implement its three abstract methods:use JMGQ\AStar\AStar; class MyAStar extends AStar { // ... public function generateAdjacentNodes(Node $node) { // Return an array of adjacent nodes } public function calculateRealCost(Node $node, Node $adjacent) { // Return the actual cost between two adjacent nodes } public function calculateEstimatedCost(Node $start, Node $end) { // Return the heuristic estimated cost between the two given nodes } // ... }
-
That's all! You can now use the
run
method in theAStar
class to generate the best path between two nodes. This method will return an ordered array of nodes, from the start node to the goal node. If there is no solution, an empty array will be returned.
There are two working implementations in the examples
folder.
In order to execute this example, run the following command:
php examples/Terrain/example.php
This example calculates the best route between two tiles in a rectangular board. Each tile has a cost associated to it, represented in a TerrainCost object. Every value in the TerrainCost array indicates the cost of entering into that particular tile.
For instance, given the following terrain:
| 0 1 2 3
-----------
0 | 1 1 1 2
1 | 1 2 3 4
2 | 1 1 1 1
The cost to enter the tile (1, 3)
(row 1, column 3) from any of its adjacent tiles is 4 units. So the real distance between (0, 2)
and (1, 3)
would be 4 units.
In order to execute this example, run the following command:
php examples/Graph/example.php
Important notes:
- This example calculates the shortest path between two given nodes in a directed graph.
- A node's position is determined by its X and Y coordinates.
- The
Link
class specifies an arc (unidirectional connection) between two nodes. For instanceLink(A, B, D)
represents an arc from the nodeA
to the nodeB
, with a distance ofD
units.
Contributions to this project are always welcome. If you want to make a contribution, please fork the project, create a feature branch, and send a pull request.
To ensure a consistent code base, please make sure your code follows the following conventions:
- The code should follow the standards defined in the PSR-2 document.
- Use camelCase for naming variables, instead of underscores.
- Use parentheses when instantiating classes regardless of the number of arguments the constructor has.
- Write self-documenting code instead of actual comments (unless strictly necessary).
In other words, please imitate the existing code.
This project has been developed following the TDD principles, and it strives for maximum test coverage. Therefore, you are encouraged to write tests for your new code. If your code is a bug fix, please write a test that proves that your code actually fixes the bug.
If you don't know how to write tests, please don't be discouraged, and send your pull request without tests, I will try to add them myself later.
Feel free to add yourself to the list of contributors.
Read the changelog.