Download the PHP package reallifekip/grid-map without Composer
On this page you can find all versions of the php package reallifekip/grid-map. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download reallifekip/grid-map
More information about reallifekip/grid-map
Files in reallifekip/grid-map
Package grid-map
Short Description A lightweight grid-based area mapping library for defining rectangular regions in a cell grid.
License MIT
FAQ
Example:
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 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.
Informations about the package grid-map
GridMap
Language: English | 繁體中文
A lightweight PHP micro-library for grid slicing. It divides a fixed-size plane (e.g., 1920×1080 canvas, video wall, media composition, dashboard, or layout system) into a grid according to specified proportions, then sequentially "fills" rectangular slices into available cells and returns their pixel coordinates and sizes.
GridMap uses a simple row-major first-fit scanning algorithm to find the first available area that can fit a slice of the requested column/row span. If successful, the area is marked as occupied and the next slice is processed. If a slice cannot fit, or if the grid is not fully occupied at the end, an exception is thrown.
✨ Features Overview
- ✅ Single static class, easy to understand and integrate
- ✅ Pure PHP ≥ 8.0 with typed, immutable DTOs
- ✅ Define slices in "grid units" and automatically convert to pixel coordinates
x, y, width, height - ✅ Deterministic first-fit placement, reproducible results
- ✅ Uses integer division
intdivto avoid floating-point rounding errors - ✅ Automatically detects unplaceable or unfilled slices and throws clear exceptions
- ✅ Suitable for dynamic layouts, video walls, auto-layout suggestions
📦 Installation
🚀 Quick Start
Example output:
Width/height are actual pixels, calculated via
intdiv. For example:1920/24 = 80,1080/12 = 90. A 6-column span = 6 × 80 = 480 px; a 6-row span = 6 × 90 = 540 px.
🧠 Core Concept
| Term | Description |
|---|---|
imageWidth, imageHeight |
Total canvas size (pixels) |
columns, rows |
Number of grid divisions (horizontal / vertical) |
Cell colSpan, rowSpan |
Slice rectangle defined in grid units, not pixels |
return Slice[] |
Each placed slice object with x, y, width, height (px) |
Config defaults
| Property | Default |
|---|---|
imageWidth |
2500 |
imageHeight |
1686 |
columns |
24 |
rows |
12 |
Steps (simplified):
- Compute all grid line coordinates:
cols[x] = intdiv(x * imageWidth, columns),rows[y] = intdiv(y * imageHeight, rows) - Use a 1D array to mark whether each cell is occupied
- For each
Cell:- Scan row-major for the first fitting location
- Check that all covered cells are free
- Mark occupied and convert to a pixel
Slice
- Throw
\Exceptionif a cell cannot be placed - Throw
\Exceptionif the grid is not fully occupied after all cells are placed
✅ Example Use Cases
| Use Case | Description |
|---|---|
| Media/Video wall | Automatically arrange multiple video sources |
| Video compositing | Map multiple tracks into fixed canvas coordinates |
| Realtime dashboard | Auto-generate initial layouts for widget cards |
| Game/Level editor | Plan map or scene block placements |
| Ad screen layout | Place multiple ad creatives into grid layout |
🛠️ Advanced Example: Mixed Sizes & Error Handling
⚠️ Notes
- Each
Cellmust have two positive integers:colSpanandrowSpan colSpancannot exceedcolumns;rowSpancannot exceedrows- Strategy is "first feasible placement": not optimized for space, just deterministic
- For "optimal packing / rotation / reordering", preprocess cells (e.g., sort by size)
- The returned
Slice[]array indexes correspond 1-to-1 with the inputcellsorder - All cells must collectively fill the entire grid — a partially filled grid throws an
\Exception
🔍 Return Data Format
Returns an array of Slice objects:
🧪 Testing Suggestions
You may write PHPUnit tests to verify:
- Slice count matches returned array count
- No overlapping rectangles (check cell intersections)
- When all cells fit, occupied grid count =
columns * rows - Oversized cells trigger
\Exception - Partially filled grids trigger
\Exception
📄 License
This package uses the MIT License – Free for commercial use / modification / distribution, just keep copyright notice.
👤 Developer Info
Author: Kip ([email protected]) GitHub: @ReallifeKip
If this project helps you: feel free to Star, share, or suggest improvements!
