|
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