Security Notice:
This setup is ONLY suggested for LOCAL DEVELOPMENT PURPOSES!!!
This post makes a couple of assumptions.
The goal of this write up is to provide a very simple, but very efficient way to use git, github, and a local server for php development. The key to this setup is tying your local vhost to your local git repo. Many new folks to web development have a hard time due to using cpanel etc for their actual site and do not know how to create a local mirror for development. Cpanel automates the host/vhost creation and in the process it hides several of the key points that could hang you up if you are not familiar with the way virtual hosting is setup server side.
So how does it relate?
The actual project files, depending on your tooling configuration, can live anywhere on your system. I suggest that the shorter your local path the fewer typos you will have which can lead to a lot of frustration for newcomers. So let's take a look into what is best practice. Couple of points here.
Let's say you are developing in windows and you have a path like this to where you want to store ALL of your projects:
C:\htdocs
and we want to create a local only host name so that apache can serve this project via something other than localhost, or 127.0.0.1. This is how you can setup more than 1 project on your local.
If this is what you have then you can move on.
So, now we need to edit the host record to create a hostname (local only) so our project can be served by apache.
Open (as an administrator)
C:\Windows\System32\drivers\etc\hosts
You need an entry like this:
Now, look up how to create a vhost for whichever local server you are running. You will need an entry similar to following. Be sure to change the your-project-name in both paths to reflect your project folder.
In the /public directory as a sibling of index.php create a .htaccess file with the following contents (it's just one I use most often from a laminas project, because it simply works for me).
Make sure all of your files have been saved and restart apache.
Open index.php in vscode and type the following:
Save the file. Commit it to the local repo, then push it to github.
Open a web browser and enter the following (if you used the example.local hostname from above)
At which time you should be presented with:
Deep dive:
The reason I like and use this particular workflow is because it allows me to rapidly create a new project. Once the project is created you have full git functionality within the project which means if you have an idea you want to try out without it affecting what you're currently working on just branch. Your branch will then be immediately available and reflected in what is served in the browser. You do not have to copy files from your github projected that you cloned into the docroot of your server or vice-versa to commit and push them to github. It's all right there.
A few notes:
I hope this helps take some of the mystery out of how to get these tools to work together in a productive way for those trying to learn to code. If you have any questions or see a mistake or something that can be improved please post it up
This setup is ONLY suggested for LOCAL DEVELOPMENT PURPOSES!!!
This post makes a couple of assumptions.
- That you have a working local server like Xammp or Wamp.
- That you have a Github account and you have Git installed on your local machine
- That you are using VSCode or something similar
The goal of this write up is to provide a very simple, but very efficient way to use git, github, and a local server for php development. The key to this setup is tying your local vhost to your local git repo. Many new folks to web development have a hard time due to using cpanel etc for their actual site and do not know how to create a local mirror for development. Cpanel automates the host/vhost creation and in the process it hides several of the key points that could hang you up if you are not familiar with the way virtual hosting is setup server side.
So how does it relate?
The actual project files, depending on your tooling configuration, can live anywhere on your system. I suggest that the shorter your local path the fewer typos you will have which can lead to a lot of frustration for newcomers. So let's take a look into what is best practice. Couple of points here.
- Only publicly accessible files should live in the docroot. Usually in php this means your index.php file and any public assets like script files, images etc.
- Many applications that you may work with over time expect to be served from the docroot. This is due to the way your web server (in this case apache) available to the client. In short, if it's not served from the doc root you can end up having a lot of issues with your urls not resolving correctly. This is a simplification of the subject matter, but covering it in-depth is beyond the scope of this post.
- When developing a web hosted application your local file path, that which is your docroot and your public web path will intersect at the docroot.
Let's say you are developing in windows and you have a path like this to where you want to store ALL of your projects:
C:\htdocs
and we want to create a local only host name so that apache can serve this project via something other than localhost, or 127.0.0.1. This is how you can setup more than 1 project on your local.
- Create your project in Github
- Clone your project to C:\htdocs (Vscode tip: with vscode open just hit cntrl + shift + p and select git clone)
- Create a directory in your project /public (this will be the docroot).
- Create an index.php in the /public directory so that you have /public/index.php. Once created you can commit this file and push it to Github.
Code:
C:\htdocs
\your-project-name
\public
\index.php
If this is what you have then you can move on.
So, now we need to edit the host record to create a hostname (local only) so our project can be served by apache.
Open (as an administrator)
C:\Windows\System32\drivers\etc\hosts
You need an entry like this:
Code:
127.0.0.1 example.local
::1 example.local
Now, look up how to create a vhost for whichever local server you are running. You will need an entry similar to following. Be sure to change the your-project-name in both paths to reflect your project folder.
Code:
<VirtualHost *:80>
ServerName example.local
DocumentRoot "c:/htdocs/your-project-name/public"
<Directory "c:/htdocs/your-project-name/public/">
Options +Indexes +Includes +FollowSymLinks +MultiViews
AllowOverride All
Require local
</Directory>
</VirtualHost>
In the /public directory as a sibling of index.php create a .htaccess file with the following contents (it's just one I use most often from a laminas project, because it simply works for me).
Code:
RewriteEngine On
# The following rule allows authentication to work with fast-cgi
RewriteRule ^ - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
# The following rule tells Apache that if the requested filename
# exists, simply serve it.
RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^ - [NC,L]
# The following rewrites all other queries to index.php. The
# condition ensures that if you are using Apache aliases to do
# mass virtual hosting, the base path will be prepended to
# allow proper resolution of the index.php file; it will work
# in non-aliased environments as well, providing a safe, one-size
# fits all solution.
RewriteCond $0::%{REQUEST_URI} ^([^:]*+(?::[^:]*+)*?)::(/.+?)\1$
RewriteRule .+ - [E=BASE:%2]
RewriteRule .* %{ENV:BASE}index.php [NC,L]
Make sure all of your files have been saved and restart apache.
Open index.php in vscode and type the following:
Code:
<?php
declare(strict_types=1);
echo 'Hello from your new vhost';
Save the file. Commit it to the local repo, then push it to github.
Open a web browser and enter the following (if you used the example.local hostname from above)
Code:
http://example.local
At which time you should be presented with:
In the browser window.Hello from your new vhost
Deep dive:
The reason I like and use this particular workflow is because it allows me to rapidly create a new project. Once the project is created you have full git functionality within the project which means if you have an idea you want to try out without it affecting what you're currently working on just branch. Your branch will then be immediately available and reflected in what is served in the browser. You do not have to copy files from your github projected that you cloned into the docroot of your server or vice-versa to commit and push them to github. It's all right there.
A few notes:
- Your local file path and your web path coincide at the docroot. Your web path begins at the docroot. Above we used /public as the docroot, which means that the corresponding segment of your web path is just / . So following the above setup if you have a local path of C:\htdocs\your-project-name\public\img for storing images, then the web path to that location on the web becomes /img. Or the full path with request scheme and host becomes http://example.local/img
- Once this setup is in place, say with vscode if you have composer setup globally on your system, you can simply open the terminal window in vscode and type composer init and step through the init prompts and create a composer project. Then install your dependencies and commit your composer.json files and push them to github.
- For those working in projects like SMF or trying too, this helps a lot. How? Set your project up and let your master/main branch serve as your clean build state. When you want to start a new mod or theme, create a new branch from the master/main repo and your good to go as long as you have a clean db to work from. I have a reset script for SMF somewhere if you need it.
I hope this helps take some of the mystery out of how to get these tools to work together in a productive way for those trying to learn to code. If you have any questions or see a mistake or something that can be improved please post it up
Last edited: