These labs assume you are using Linux and that you have at least seen a programming language in action. There will be, at times, a line-by-line explanation of what is going on in the code. This can be painful to established programmers due to its remedial nature. Keep in mind that LIMSExpert.com readership includes individuals that do not program for a living. There will be an attempt to keep this to a minimum with references to good online and offline resources. One should assume that the difficulty level of most labs will be somewhere between beginner and intermediate with exceptions to this noted early in the text.
Please note that there will be a periodic, albeit unreliable, smattering of Windows-specific instructions on occasion but for consistency you should not rely upon this being available. If you are in need of a Linux distribution recommendation try using a LiveCD that already has PHP and a webserver installed. In the future parts of these labs will be recorded so you can follow along more easily. If you run into a problem check the Contact page and send off an e-mail asking for assistance.
Let's Get Started
Fetch the code from the Downloads page under Series A (the one with lab-a1-001.tar.gz). A common mistake when trying to run some code on Linux is to forget to check your file permissions. In order for the code to be runnable from a web-server it has to at least be readable by the user that is running the server process. You can find out who that is by running something like this,
ps -ef|grep apache
if you are running the Apache server. In my case the apache2 server is being run by the www-data user. Let's ensure that the files in our project are world-readable and are at least usable by that user:
tar -zxvf lab-a1-001.tar.gz
ls *.php|sudo xargs chmod 644
ls *.php|sudo xargs chgrp www-data
By the way, it helps if you actually have PHP installed. Check it:
You should see the PHP version number and build information.
Unboxing and First Steps
You'll notice the files are arranged in a particular order:
Classes go in the ./lib directory; tests in the ./test directory, and our entry-point files go in the core directory. There will eventually be places to put configuration files, etc. but for now we'll concentrate on these.
You don't need a fancy editor to open these files. If you are a novice you might just try GEdit. It is probably already on your system so look around for it. Go into the ./lib folder and open UserAccess.php. Notice that it does not contain anything other than the class. The other class files in this directory are the same. We'll get into strategies for grouping our code into chunks (namespaces/folders) in a later lab. Here we just want to get into the habit of differentiating between an entry point and a library and introduce the concept of test-driven development.
Our objective is to run tests on the command line from the ./test directory. Eventually we want to be able to run tests in a purely automated fashion from a scheduler. That way we can identify problems early during development rather than at later steps.
No code should be produced without tests. This example is actually a bad one since not every branch of executable code in the package contains its own test. For instance, in DataAccessor.php Line 15 there is a conditional statement that could go either way. There should be a test for that.
Lots of LIMS were written long before test-driven development became popular, so there are hundreds of thousands of lines of code floating around out there where no comprehensive regression test is actually possible. That is why each successive round of developers that work on the code tend to destabilize the system just a little further. Thorough automated testing virtually eliminates this problem. You will see this for yourself as we progress.
Putting tests in their own directory helps in environments where there are rules prohibiting code that is not actually meant to be used day-to-day (like in regulated industries for instance). In such a case you could simply remove the ./test folder entirely on a production system and keep it on development and test instances.
The first thing you'll notice is that there are no documents in here and that is not a good thing. You want specifications, designs, and documentation references explaining the project's direction, specifying what will be out of scope, and what it should look like when it is completed.
Since we have not yet gone into ways to produce terse but effective documentation this has been purposefully left out for later labs. As we code we have multiple consumers -- the frameworks/language suites/operating system itself and the other developers on the project. When developing it is all too easy to concentrate on the fore and forget about the latter. What our documentation needs early on is to communicate at a minimum to developers and system architects. We will go into strategies to keep it to a minimum while maintaining flexibility.
Exercises and Reading for Next Lab
So in this lab you have done the following:
- a) Found the correct download section and downloaded the file(s) using the naming format
- b) Recognized the structure of libraries and main code
- c) Found the test directory
Citation: LAB-A1-001 - Labs. (2015). Retrieved Thu Mar 23 00:13:56 2017, from http://www.limsexpert.com/cgi-bin/bixchange/bixchange.cgi?pom=limsexpert3;iid=readMore;go=1440192936