State vs Status API guide

Today I had to make the choice whether I would use the word state or status in my program API, and I got confused. What is actually the difference?

This is not about states in the sense of the United States, but about the condition of something.

As an example, I will use the condition of the "something" called H²O, also known as water.

Luckily we as programmers are already familiar with the concept of a definition (class) and an instance (object). With state and status it's the same. State is a definition, and status is an instance of that definition.

So, H²O has several states, namely; Solid, Liquid and Gas. Solid is one state of the 3 states in which H²O can be. If we would query for the state of a H²O substance, then we would ask for its status. Like, Q: "What is the status of this 'water'?", A: "It's in a solid state, it's ice.".

In an API, you would have to stick to the right naming, because it can confuse the use of the API. Let me show you with an example in C#:

   enum H2OStates
   {
       Solid,
       Liquid,
       Gas
   }

   class H2O
   {
       public const H2OStates IceState = H2OStates.Solid;
       public const H2OStates WaterState = H2OStates.Liquid;
       public const H2OStates VaporState = H2OStates.Gas;

       public H2OStates Status;
   }

The confusion will probably occur with the definition of the H2O class. When you have a H2O object, something that comes to mind is to ask the question "What is the state of this H²O?". The property to return the state, should not be called State, but Status. Why? Because it could return any of the possible states, and not a single hard-coded state value of the H²O, like it is with the constants in the H2O class. Those constants should be named with State in stead of Status, because they always return the same static value, and not an item within a range of possible values.

But now I hear you ask, what about statuses? That's nothing more than a bunch of H2O instances with each having their Status property referring to a specific state.

PHP's _SERVER["DOCUMENT_ROOT"] no good for filesystem path with virtual directories

One thing that can bring a serious headache is if you use the PHP variable $_SERVER["DOCUMENT_ROOT"] to open files in the file system and your site is placed in an Virtual Directory in IIS.

This server variable points to the root of the server and this is not necessarily the path the virtual directory points to.

Of course this solution could work in the right conditions; hosted on a web server and placed in a physical directory under this path. However, if you want to have a flexible application and avoid issues if it is placed in a virtual directory, then do not use this variable.

An alternative could be to use:

dirname(__FILE__)

This method with the provided constant will return the directory where the current script file (also for included files) is located. Then you can point to this path relatively if it is a well known location such as your application root. Another benefit is that this constant is always available, as the _SERVER[] constants are depending on the host.

So here's my advise: try to avoid using the $_SERVER["DOCUMENT_ROOT"] variable for paths and use physical paths instead.