|
1 | 1 | +++
|
2 |
| -title = "Getting Started & Developer Experience" |
3 |
| -weight = 1 |
| 2 | +title = "Phel: A Functional Lisp Dialect for PHP Developers" |
4 | 3 | +++
|
5 | 4 |
|
6 |
| -## Requirements |
| 5 | +**Phel** is a functional programming language that compiles down to PHP. It's a modern Lisp dialect inspired by [Clojure](https://clojure.org/) and [Janet](https://janet-lang.org/), tailored to bring functional elegance and expressive code to the world of PHP development. |
7 | 6 |
|
8 |
| -Phel requires PHP 8.2 or higher and [Composer](https://getcomposer.org/). |
| 7 | +<p align="center"> |
| 8 | + <img src="/images/logo_phel.svg" width="350" alt="Phel language logo"/> |
| 9 | +</p> |
9 | 10 |
|
10 |
| ---- |
| 11 | +## Join the Phel Developer Community |
11 | 12 |
|
12 |
| -## Quick Start with a Scaffolding Template |
| 13 | +Got questions? Want to chat about macros, tail recursion, or why parentheses are awesome? |
| 14 | +Swing by the [Phel Gitter channel](https://gitter.im/phel-lang/community)—we're friendly, nerdy, and always happy to talk code. |
13 | 15 |
|
14 |
| -You can create a new Phel commandline project via Composer’s `create-project` command: |
| 16 | +## Key Features of Phel |
15 | 17 |
|
16 |
| -```bash |
17 |
| -composer create-project --stability dev phel-lang/cli-skeleton example-app |
18 |
| -cd example-app |
19 |
| -composer repl |
20 |
| -``` |
21 |
| - |
22 |
| -> Alternatively, use [phel-lang/web-skeleton](https://github.com/phel-lang/web-skeleton) for a web project. More details in the [README](https://packagist.org/packages/phel-lang/cli-skeleton). |
23 |
| -
|
24 |
| ---- |
25 |
| - |
26 |
| -## Manual Setup with Composer |
27 |
| - |
28 |
| -1. Initialize a new project: |
29 |
| - |
30 |
| -```bash |
31 |
| -mkdir hello-world |
32 |
| -cd hello-world |
33 |
| -composer init |
34 |
| -``` |
35 |
| - |
36 |
| -2. Require Phel: |
37 |
| - |
38 |
| -```bash |
39 |
| -composer require phel-lang/phel-lang |
40 |
| -``` |
41 |
| - |
42 |
| -> Optionally create `phel-config.php`: |
43 |
| -> ```php |
44 |
| -> <?php |
45 |
| -> return (new \Phel\Config\PhelConfig())->setSrcDirs(['src']); |
46 |
| -> ``` |
47 |
| -> See all [configuration options](/documentation/configuration). |
48 |
| -
|
49 |
| -3. Create the source directory and a file: |
50 |
| -
|
51 |
| -```bash |
52 |
| -mkdir src |
53 |
| -``` |
54 |
| -
|
55 |
| -4. Write your first Phel program: |
56 |
| - |
57 |
| -```phel |
58 |
| -;; src/main.phel |
59 |
| -(ns hello-world\main) |
60 |
| -(println "Hello, World!") |
61 |
| -``` |
62 |
| - |
63 |
| ---- |
64 |
| - |
65 |
| -## Running the Code |
66 |
| - |
67 |
| -### From the Command Line |
68 |
| - |
69 |
| -```bash |
70 |
| -vendor/bin/phel run src/main.phel |
71 |
| -# or |
72 |
| -vendor/bin/phel run hello-world\\main |
73 |
| -# or |
74 |
| -vendor/bin/phel run "hello-world\main" |
75 |
| -``` |
76 |
| - |
77 |
| -Output: |
78 |
| - |
79 |
| -``` |
80 |
| -Hello, World! |
81 |
| -``` |
82 |
| - |
83 |
| -### With a PHP Server |
84 |
| - |
85 |
| -```php |
86 |
| -// src/index.php |
87 |
| -<?php |
88 |
| - |
89 |
| -use Phel\Phel; |
90 |
| - |
91 |
| -$projectRootDir = __DIR__ . '/../'; |
92 |
| - |
93 |
| -require $projectRootDir . 'vendor/autoload.php'; |
94 |
| - |
95 |
| -Phel::run($projectRootDir, 'hello-world\\main'); |
96 |
| -``` |
97 |
| - |
98 |
| -Start the server: |
99 |
| - |
100 |
| -```bash |
101 |
| -php -S localhost:8000 ./src/index.php |
102 |
| -``` |
| 18 | +Why code in Phel? Here's what makes it click: |
103 | 19 |
|
104 |
| -Visit [http://localhost:8000](http://localhost:8000) to see the output. |
| 20 | +- ✅ Runs on the rock-solid PHP ecosystem |
| 21 | +- 🧠 Helpful and human-readable error messages |
| 22 | +- 📚 Built-in persistent data structures: Lists, Vectors, Maps, Sets |
| 23 | +- 🧩 Macro system for advanced metaprogramming |
| 24 | +- 🔁 Tail-recursive function support |
| 25 | +- ✨ Minimal, readable Lisp syntax |
| 26 | +- 💬 Interactive REPL for tinkering and prototyping |
105 | 27 |
|
106 |
| -> Consider using `phel build` for performance. See [Build the project](/documentation/cli-commands/#build-the-project). |
| 28 | +## Why Choose Phel for Functional Programming in PHP? |
107 | 29 |
|
108 |
| ---- |
| 30 | +Phel started as an [experiment in writing functional PHP](/blog/functional-programming-in-php) and quickly turned into its own thing. |
109 | 31 |
|
110 |
| -## Launch the REPL |
| 32 | +It exists because we wanted: |
111 | 33 |
|
112 |
| -Start an interactive REPL in any project with Phel installed: |
| 34 | +- A Lisp-inspired functional language |
| 35 | +- That runs on affordable PHP hosting |
| 36 | +- That's expressive, debug-friendly, and easy to pick up |
113 | 37 |
|
114 |
| -```bash |
115 |
| -./vendor/bin/phel repl |
116 |
| -``` |
| 38 | +If you've ever wished PHP was a bit more... functional, Phel is for you. |
117 | 39 |
|
118 |
| -You can evaluate Phel expressions: |
| 40 | +## See Phel in Action — Sample Code |
119 | 41 |
|
120 | 42 | ```phel
|
121 |
| -phel:1> (def name "World") |
122 |
| -phel:2> (println "Hello" name) |
123 |
| -Hello World |
124 |
| -``` |
125 |
| - |
126 |
| -The REPL understands multi-line expressions and supports `doc`, `require` and `use` helpers. |
127 |
| - |
128 |
| -> More in the [REPL documentation](/documentation/repl). |
129 |
| -
|
130 |
| ---- |
131 |
| - |
132 |
| -## Debugging Helpers |
133 |
| - |
134 |
| -Use PHP debugging tools: |
135 |
| - |
136 |
| -```phel |
137 |
| -(def result (+ 40 2)) |
138 |
| -(php/dump result) |
139 |
| -``` |
140 |
| - |
141 |
| -Enable temporary PHP files for inspection: |
142 |
| - |
143 |
| -```php |
144 |
| -// phel-config-local.php |
145 |
| -return (require __DIR__ . '/phel-config.php') |
146 |
| - ->setKeepGeneratedTempFiles(true); |
147 |
| -``` |
| 43 | +# Define a namespace |
| 44 | +(ns my\example) |
148 | 45 |
|
149 |
| -> Learn more on the [Debug page](/documentation/debug). |
| 46 | +# Create a variable |
| 47 | +(def my-name "world") |
150 | 48 |
|
151 |
| ---- |
| 49 | +# Define a function |
| 50 | +(defn print-name [your-name] |
| 51 | + (print "hello" your-name)) |
152 | 52 |
|
153 |
| -## Building and Deploying |
154 |
| - |
155 |
| -Run directly: |
156 |
| - |
157 |
| -```bash |
158 |
| -vendor/bin/phel run src/main.phel |
159 |
| -``` |
160 |
| - |
161 |
| -Build for production: |
162 |
| - |
163 |
| -```bash |
164 |
| -php phel build |
165 |
| -php out/index.php |
| 53 | +# Call the function |
| 54 | +(print-name my-name) |
166 | 55 | ```
|
167 | 56 |
|
168 |
| -> More in the [CLI commands](/documentation/cli-commands/#run-a-script). |
169 |
| -
|
170 |
| ---- |
| 57 | +If you know Lisp or Clojure, you'll feel right at home. If you don't—this is a great place to start. |
171 | 58 |
|
172 |
| -## Testing |
| 59 | +## Try Phel Instantly with Docker |
173 | 60 |
|
174 |
| -Run Phel tests: |
| 61 | +No setup? No problem. You can run Phel's REPL right away: |
175 | 62 |
|
176 | 63 | ```bash
|
177 |
| -vendor/bin/phel test --filter foo |
| 64 | +docker run -it --rm phellang/repl |
178 | 65 | ```
|
179 | 66 |
|
180 |
| -Run PHP-based tests: |
181 |
| - |
182 |
| -```bash |
183 |
| -composer test |
184 |
| -``` |
185 |
| - |
186 |
| -> More in the [Testing section](/documentation/testing). |
187 |
| -
|
188 |
| ---- |
189 |
| - |
190 |
| -## Handy Macros |
191 |
| - |
192 |
| -Example: |
193 |
| - |
194 |
| -```phel |
195 |
| -(when condition |
196 |
| - (println "only printed when condition is true")) |
197 |
| -
|
198 |
| -(-> {:name "Phel"} |
199 |
| - (:name) |
200 |
| - (str "Lang")) |
201 |
| -``` |
| 67 | + |
202 | 68 |
|
203 |
| -These macros keep code concise and readable. Explore the rest of the library for more utilities. |
| 69 | +## Get Started with Phel in Minutes |
204 | 70 |
|
205 |
| -> See the [Macros page](/documentation/macros) for more. |
| 71 | +All you need is [PHP >=8.2](https://www.php.net/) and [Composer](https://getcomposer.org/). |
206 | 72 |
|
207 |
| ---- |
| 73 | +> Follow our [Getting Started Guide](/documentation/getting-started) to build and run your first Phel program today. |
208 | 74 |
|
209 |
| -## Editor Support |
| 75 | +## Development Status & How to Contribute |
210 | 76 |
|
211 |
| -Phel supports: |
| 77 | +Phel is approaching its 1.0 release, but we're still actively refining the language —and yes, breaking changes may happen. |
212 | 78 |
|
213 |
| -- [VSCode extension](https://github.com/phel-lang/phel-vs-code-extension) |
214 |
| -- [PhpStorm syntax plugin](https://github.com/phel-lang/phel-phpstorm-syntax) |
215 |
| -- [Emacs interactive mode](https://codeberg.org/mmontone/interactive-lang-tools/src/branch/master/backends/phel) |
216 |
| -- [Vim plugin (in progress)](https://github.com/danirod/phel.vim) |
| 79 | +We're building this in the open. That means: |
| 80 | +- Found a bug? File an issue. |
| 81 | +- Got a cool idea? Open a pull request. |
| 82 | +- Want to shape the language's future? Let's talk. |
217 | 83 |
|
218 |
| -> Details also in the [Editor Support](/documentation/getting-started/#editor-support) section. |
| 84 | +Your feedback, ideas, and code help Phel grow into something great. |
0 commit comments