PHPackages ryangaudet/crossword-grid-builder - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. ryangaudet/crossword-grid-builder ActiveLibrary[Utility & Helpers](/categories/utility) ryangaudet/crossword-grid-builder ================================= A PHP backtracking algorithm that builds crossword puzzle grids from word lists. 00PHP Since Apr 4Pushed 3mo agoCompare [ Source](https://github.com/RyanG2016/crossword-grid-builder)[ Packagist](https://packagist.org/packages/ryangaudet/crossword-grid-builder)[ RSS](/packages/ryangaudet-crossword-grid-builder/feed)WikiDiscussions main Synced today READMEChangelogDependenciesVersions (1)Used By (0) Crossword Grid Builder ====================== [](#crossword-grid-builder) A PHP backtracking algorithm that builds crossword puzzle grids from word lists. Give it words, get back a valid crossword layout. **See it in action at [CodeXword](https://codexword.dev)** — crossword puzzles for people who code. How It Works ------------ [](#how-it-works) The algorithm uses **recursive backtracking with scoring** to find optimal word placements: 1. Words are sorted longest-first (harder to place, so they go early) 2. The first word is placed horizontally at the center of the grid 3. For each subsequent word, the algorithm finds all positions where it shares a letter with an already-placed word (intersection) 4. Candidates are scored by number of intersections and proximity to center 5. The algorithm recursively tries each candidate, backtracking if it leads to a dead end 6. If the first ordering fails, it retries with shuffled orderings (up to 10 attempts) 7. A configurable timeout prevents infinite loops on impossible layouts Installation ------------ [](#installation) ``` composer require ryangaudet/crossword-grid-builder ``` Usage ----- [](#usage) ### Basic [](#basic) ``` use RyanGaudet\CrosswordGridBuilder\GridBuilder; $builder = new GridBuilder(); $words = ['FUNCTION', 'CLASS', 'RETURN', 'WHILE', 'ARRAY', 'STRUCT', 'ENUM', 'GUARD']; $result = $builder->build($words, 11); // 11x11 grid if ($result) { // $result['grid'] — 2D array of characters ('#' = empty, 'A'-'Z' = letter) // $result['placements'] — array of placed words with positions foreach ($result['placements'] as $placement) { echo "{$placement['word']} at [{$placement['row']}][{$placement['col']}] {$placement['direction']}\n"; } // Print the grid echo $builder->toString($result['grid']); } ``` Output: ``` . . . . . R . S . . . . W H I L E . W . . . . . . . . T . I . . . . . S T R U C T . . . . . . U . R . C . . . . . . P . N . H . . . . . . L . . . . . . . . . . E N U M . . . . . . . . . . . . . . . ``` ### Auto-sized Grid [](#auto-sized-grid) Let the library calculate the optimal grid size based on your longest word: ``` $result = $builder->buildAuto($words); echo "Grid size: {$result['gridSize']}x{$result['gridSize']}\n"; echo "Words placed: " . count($result['placements']) . "/" . count($words) . "\n"; ``` ### Configuration [](#configuration) ``` // Custom timeout (default 5 seconds) and minimum word count (default 6) $builder = new GridBuilder( timeoutSeconds: 3.0, minWords: 4, ); ``` ### Grid Sizing [](#grid-sizing) The `GridSizer` utility calculates grid dimensions based on the longest word: ``` use RyanGaudet\CrosswordGridBuilder\GridSizer; $size = GridSizer::fromWords(['FUNCTION', 'CLASS', 'RETURN']); // Returns 11 (FUNCTION is 8 chars → 11x11 grid) ``` Longest WordGrid Size3-5 letters9x96-8 letters11x119-11 letters13x1312+ letters15x15Placement Data -------------- [](#placement-data) Each entry in `$result['placements']` contains: ``` [ 'word' => 'FUNCTION', // The placed word (uppercase) 'row' => 3, // Starting row (0-indexed) 'col' => 2, // Starting column (0-indexed) 'direction' => 'across', // 'across' or 'down' ] ``` Algorithm Details ----------------- [](#algorithm-details) The placement scoring considers: - **Intersections** (50 pts each) — more shared letters = more connected grid - **Center proximity** (up to 20 pts) — words closer to center look better Validation rules per cell: - A cell can only contain one letter (intersections must match) - No parallel adjacency (prevents unintended word formation) - No run-on (empty cell or edge required before and after each word) The algorithm guarantees: - All placed words are fully connected (share at least one intersection) - No cell conflicts - Minimum word count met (configurable, default 6) - Completes within the timeout (configurable, default 5s) Requirements ------------ [](#requirements) - PHP 8.1+ Testing ------- [](#testing) ``` composer install composer test ``` License ------- [](#license) MIT License. See [LICENSE](LICENSE). About ----- [](#about) This algorithm powers [CodeXword](https://codexword.dev) — a crossword puzzle platform where every puzzle is built around programming terminology. 9 languages, 72 themes, from Beginner to Advanced. Built by [Ryan Gaudet](https://github.com/RyanG2016). ### Health Score 18 — LowBetter than 8% of packages Maintenance55 Moderate activity, may be stable Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity12 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/6e521a9ca2cb0b4fa923c06419038db3c15fbc64dca057a40a36ed79c0ac14ca?d=identicon)[RyanGaudet](/maintainers/RyanGaudet) --- Top Contributors [![RyanG2016](https://avatars.githubusercontent.com/u/24438035?v=4)](https://github.com/RyanG2016 "RyanG2016 (1 commits)") --- Tags algorithmbacktrackingcomposer-packagecrosswordcrossword-generatorgridopen-sourcephppuzzleword-game ### Embed Badge ![Health badge](/badges/ryangaudet-crossword-grid-builder/health.svg) ``` [![Health](https://phpackages.com/badges/ryangaudet-crossword-grid-builder/health.svg)](https://phpackages.com/packages/ryangaudet-crossword-grid-builder) ``` ### Alternatives [kornrunner/ethereum-address Pure PHP Ethereum Address Generator / Validator 42120.7k10](/packages/kornrunner-ethereum-address)[jawira/plantuml Provides PlantUML executable and plantuml.jar 21395.9k10](/packages/jawira-plantuml)[attestto/solana-php-sdk Solana PHP SDK for interacting with the Solana blockchain 5638.7k](/packages/attestto-solana-php-sdk)[interaction-design-foundation/laravel-geoip Support for multiple Geographical Location services. 19267.9k3](/packages/interaction-design-foundation-laravel-geoip) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)