F.E.L.T.

Functionally Equivalent Language Translation

Installing for Web Development

Before continuing, make sure that you have first followed the instructions for installing for CLI development and have a working FELT environment.

Whilst the information contained herein aims to be as up to date and as accurate as possible it cannot possibly cover all of the different variations in OS and hardware that people use. FELT was developed on Linux with Emacs and a host of very very useful open source tools for code preparation, documentation etc. Whilst every endeavour has been made to take into account cross platform differences here and there, you will appreciate that, for now at least, FELT is the work of one person in his own time and therefore you may find what you consider to be "holes" in the documentation set. If that is that case then please do not hesitate to contact me via the site, stating your issues, and I will attempt to address them in a way that benefits as many other people at the same time.

This means that I may not answer your question personally but may produce some new feature / option / documentation etc. and then make it available on the site. I will however always respond to your email personally.

As I have now mentioned, I am a Linux addict however I am also fortunate to own a Mac which means that I am aware of what is required to get it working on that platform as well. It is Unix but there are differences. As for Windows... I don't use it professionally or personally but I will cover that as well as it seems only fair to include it as well for completeness but I will only be able to give you a high level guide and how to get it up and running, for which I recommend that you either install:

I can personally recommend that latter; I have implemented many Drupal sites on Windows solutions using it and I can think of no better way to get FELT up and running on a Windows box.

PHP Version Requirements

I have aimed the minimum level of PHP required to run felt as 5.2. This means that older hosting accounts that have not yet upgraded to 5.3 shouldn't be a problem. The current site is hosted on a PHP 5.2 server, specifically:

PHP 5.2.17 (cli) (built: Aug 13 2012 21:45:44)
Copyright (c) 1997-2010 The PHP Group
Zend Engine v2.2.0, Copyright (c) 1998-2010 Zend Technologies
    with the ionCube PHP Loader v4.2.2, Copyright (c) 2002-2012, by ionCube Ltd., and
    with Zend Optimizer v3.3.9, Copyright (c) 1998-2009, by Zend Technologies

I deliberately chose it to be this way so that the barrier to uptake was as low as possible. I had originally used PHP 5.3 anonymous functions and the ability to use func_get_args() as a parameter to other functions but I then reworked it so that using the (DEFUN*) instruction now generates a unique function name; all such functions are eventually appended to the current translation session in the post-render phase of the coder back end.

There are also some other differences that caught me out between 5.2 and 5.3, for instance the fact that the strstr() function in 5.3 has the "before needle" option but not in 5.2. I had originally used that when slicing up the phpinfo() output. Fortunately for me I am Zend certified so these things are never far from my mind and it was only a matter of time before FELT was sailing on an even keel on the chosen deployment version of 5.2!

Web-Servers

I developed the site against Apache2 server that sits on my Ubuntu box,

Server version: Apache/2.2.22 (Ubuntu)
Server built:   Feb 13 2012 01:37:27

The live site is served up by LiteSpeed and works just fine, there are not dependencies in the code that rely upon Apache that I am aware of. If you find something that doesn't work because of the technology combination that you use then get in touch using the contact form on the site and we'll see if the problem can be resolved if it seems to be "trivial" in the sense that it is a simple issue of not using a particular PHP sequence. I will not be able to entertain highly specific technical queries about platform X with software A,B,C etc. as there are just too many combinations that can cause trouble!

Apache Installation

I can help you out a little here by showing you the Apache virtual host configuration file that I have on my development machine, where I have placed the text FELT_ROOT, you must replace that with the name of the folder that you checked out the subversion repository to.

Here is my virtual host configuration file:

<VirtualHost *:80>
    ServerAdmin sean@objitsu.com
    ServerName  local.felt

    DocumentRoot FELT_ROOT
    <Directory />
        Options FollowSymLinks
        AllowOverride All
    </Directory>
    <Directory FELT_ROOT>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All
        Order allow,deny
        allow from all
    </Directory>

    ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
    <Directory "/usr/lib/cgi-bin">
        AllowOverride None
        Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
        Order allow,deny
        Allow from all
    </Directory>

    ErrorLog /var/log/apache2/error.log

    # Possible values include: debug, info, notice, warn, error, crit,
    # alert, emerg.
    LogLevel warn

    CustomLog /var/log/apache2/access.log combined
</VirtualHost>

Once you have copied the above file to wherever on your system the sites-available files are stored, you then have to, as root, issue the following commands:

$ a2ensite local.felt

  Enabling site local.felt.
  To activate the new configuration, you need to run:
  service apache2 reload

$ service apache2 reload
  * Reloading web server config apache2          [ OK ]

And then you can check that everything is well by visiting this URL in your browser: http://local.felt. if you see a greeting message then you know that you have successfully installed FELT and that it is accessible from your web server and you are now ready to develop your killer PHP application in a way that you never thought would feel so good! ;)

If you don't get the message but instead you see some other error message then all I can do is ask that you check out the Google Group forums and either see if somebody else has had and solved the same issue or post a new topic.

As usual, when posting, please be polite, read everything relevant first and then give as much detail as you can; server details, PHP version etc. There's no point asking something like "It doesn't work, please help me?" Forums all over the world are full of useless questions like that. It takes effort to ask a meaningful question, if you can't be bothered to ask a deeply detailed and reasoned question then why would anybody take the time to try to answer it? Makes me groan every time I see one...

Directory Structure

The operation of FELT includes some caching so that FELT source files are only translated into PHP when you edit and save them. If they are unchanged, then a cached version is fed to the PHP compiler for better performance. Cacheing means that when you require files using the form (require "felt://...") that the response is as fast as possible.

Cache Folder

This is the feltcache folder and MUST be present for the system to operate as intended. Ensure that this folder has all the necessary permissions and group+ownership rights that the web server on your platform expects otherwise it will not be able to create folders and files at run-time. You will soon know if this is the case as the output will fill with error messages about "permission denied".

Logs Folder

On the live site there is a function called _l() that performs simple logging to a file called trace.log. If you want to write your own logging functions then feel free but please ensure that they write into this folder to keep things nice and tidy. There is nothing more than having a bunch of ad-hoc files littering up a project. It makes maintenance very hard and shame on anybody that has (or been forced to) commit files to a repository just in case they were important because nobody really knew why there were there in the first place. Never say never...

Creating the Structure

On Ubuntu for example, the Apache2 server runs as the user www-data and I find that the following commands are best for setting up the folders, assuming that you are in the folder that you checked out the FELT release into:

$ mkdir feltcache
$ mkdir logs
$ sudo chown www-data:www-data feltcache
$ sudo chown www-data:www-data logs

On OSX and Window I imagine that using the File Browser would be the easiest option to make the necessary folders have the correct permissions.

FELT Source Files

On the live site I chose to create some folders called sitecode and sitepages. The first contains all of the FELT source for the library functions, page rendering etc. and the latter contains the actual FELT code that make sup the pages that you see. That particular arrangement was bespoke for that project and FELT gives you complete freedom to put things anywhere you like beneath the web-root.

Did you read that carefully? Please read and remember this fact:

RULE #1 -- When you require a file using the felt:// stream-wrapper, you must always name the file relative to the root of the site so that the stream wrapper can work out where what and why to open, translate and cache. Remember that, life is good.

I therefore suggest that you create a folder beneath the web-root called something like "feltcode" or "feltsrc" and one called "phpcode" or "phpsrc" so that you can keep them separate. FELT can easily re-use any PHP classes and scripts, after all it renders out as PHP. Likewise any existing code you have can call or re-use classes created with FELT, the interoperability is seamless as you would hope and expect it to be, that will be covered in more detail in the "Programming FELT for PHP" manual.

An example; "Hello World" web site.

Let's consider the above rule and create a simple one page application that merely prints out the timeless classic one more time.

Create the index.php file

As FELT is just going to be PHP once it is translated we need to "bootstrap" the system to get in installed. This means that the custom stream wrapper that performs on-the-fly translation is loaded, activated and then ready to do some work.

Here is the smallest index.php file that you need in order to create a FELT powered site:

require_once "src/toolbox/felt.core.php";
require_once "felt://feltsrc/index.felt";

That's it. The first statement locks and loads the FELT core translation code and the second statement causes the contents of that file to be read, parsed, translated into PHP, compiled into scope by the PHP compile, executed and rendered to the browser just like that!

Create the index.felt file

So, having bootstrapped the FELT core we now need to create the file cited in the second require statement, here it is:

;; A simple hello world program
(emit "Hello, World!")

There. That's it. There is a short form available for the emit instruction which kind of looks a little odd but I hate typing and I use Haskell so I like weird instructions ;) Here's the alternative version of the output:

(o> "Hello, World!")

Assuming that you have followed the instructions above then opening "http://local.felt" should produce the expected message. If it doesn't, check what you did against these instructions and if that still doesn't get it fixed go check the forums for some extra assistance.

So there we are, if you got this far then you now have a working FELT web application that does absolutely nothing much!

Generated Files

At this point if you care to examine the feltcache folder you should see a mirror of the location of the index.felt file and you can then read it and see what a horrible mess the generated PHP code looks like! I never planned to make it readable because I don't ever want to read PHP again. I like LISP and so I decided from the outset that "beautiful output code" wasn't even near the bottom of the list.

Next...

I hope that the information contained in this document has enabled you to get FELT installed and running on your development servers / local host machine and that you are now ready to explore the language and how it can be used to create a PHP driven web-site.

It can also be used to generate the Javascript and CSS as well but I suggest that you read the associated pages for more detailed information.

Please please please, if you get stuck, use the felt-hackers Google group if you have any troubles getting FELT up and running and if that fails use the contact page and provide as much information as possible. It is early days for FELT and I need your feedback to get it up to speed in the real world as quickly as possible.