Category: Development

About guide, how-to, tutorial, thought, etc that may give better understanding, opinion or something similiar

Got Hooked Playing Flight Simulator

Got Hooked Playing Flight Simulator

I always like simulator games like a farming simulator or truck simulator.

This kind of game is always kind. I mean, it doesn’t really pressure you. There’s no threat, no big issue, no challenge and sometimes funny things happen. Basically, just sit, relax and play.

Which might be boring for some people.

My first simulator game is actually truck simulator. I forgot which version is it but I play it when I was 8 years old.

When I first play that game, I don’t understand anything. It is in English but I don’t know any English back then.So what I do is just driving around the town. I don’t pick any mission, quest, or anything like that. Just driving. And I always coming back to play more.

So what I do is just driving around the town. I don’t pick any mission, quest, or anything like that. Just driving. And I always coming back to play more.

Even if I have to share it with my little brother.

The reason? I don’t know. I guess I just like having fun, looking at the environment and relaxing without worrying too much.

But due to my PC and the only PC in my home broken, I can’t play it anymore. My parent bought PS1 for me (and my brother), but there is no simulator game on that platform. At least there is no store nearby that sell simulator game.

From that day, I don’t play simulator game anymore. It’s not like I lose interest, I just forgot that this kind of genre exists.

At least until recently.

I look at my Steam library and store recommendation recently, looking for a game to play. When I go through my Steam queue, I got directed to the new x-plane game (x-plane 11). I don’t know why, but I got little interested in it.

I never play flight simulator games. They look hard to play and confusing. There are so many buttons I can just press but I don’t know what it does.

Not only that, there are many number and code on the screen that I don’t understand what it means. Maybe one or two, but there are too many things that I don’t understand.

I always got this strange feeling that if I press it, something bad will happen. Even if in reality, nothing will happen. You might be crashing and you just have to repeat the flight.

This kind of game is always not newbie friendly. Really hard to learn.

Sure there is a tutorial, but it explains nothing. It feels like it only guides you 3 out of 50 things you should know before you “can” play.

But strangely, I like this kind of game.

So after some thinking time, reading some reviews, guide, stream and youtube. I decide to bought it from steam, play it for a couple hours, and I love it.

My weekend is gone in the blink of an eye. Like it has been 3 days since I bought it and I already got 20 hours playing it. I guess that happen when you don’t sleep.

Because of that, I sleep like a log on Sunday night.

This happens when I really love the game. This also happens when Cities Skyline first came out. I was like “what is sleep?”.

Fortunately for me, there are not that many games that can make me lost time like that. I’m pretty good to keep control to when I should or shouldn’t play, as long as I’m not in the middle of playing. Basically, if I play, I’m gone.

So far, it really good game. I’m not that pro yet. Heck, I’m not even at an amateur level yet. My flight record is like 3 success out of 20 flight. Pretty bad.

If you like this kind of game, buy it. It good. Be warned, it addictive.

The only problem I have so far is the control. It really hard to control. Especially if you don’t have a joystick.

I only have keyboard, mouse and Xbox controller to play. Just a little, gentle push on the analog, my plane rotating aggressively.

That why I add a joystick to my next thing to buy list.

That when I realize, I got addicted.

Prettier: Javascript Formatter

Prettier: Javascript Formatter

If you have been coding javascript for a while and working with multiple people that used to use different languages. Do you ever reviewing your code project and there are many coding standards mixed up and wasting your time to reformat each file to match your coding standard. A simple example of that is using tabs vs space to indent the code.

I got this problem, especially lately when my team is growing but our team is lack people that experienced in javascript. Which is why on today post, I will introduce you all to javascript formater called Prettier.

What it do is formatting your javascript code automatically so you don’t have to waste your time, reviewing each line and files, spending an hour just to format the code which provides nothing to the product. With this tools, you got both pretty code and time to spend on the more important task (or more time to be lazy).

It works by converting your javascript code to AST (Abstract Syntax Tree) and then pretty-printing the AST which give you with pretty and formatted code. Pretty simple, I know.

Not only that, it even got an option to set which javascript format you are going to use. I know that in javascript or similar language there has been style war. If you don’t know what it is, as you know there are many different coding standards available to use in javascript and people has trouble to agree which standard is the standard. So they decide to use their own standard. If you are using coding standard that didn’t really match with Prettier default, you can change it in the option.

If you are using Atom which is a powerful editor and my favorite programming editor, you can install it on your atom package manager or use command:

There is a downside tough. There is still some bug and the options are pretty limited. But since it still a new project, give it some time. It will be better. Regardless, it is a promising project and really useful especially if you have trouble or being overwhelmed by messy code in your project.

One note on the stability. Based on their blog post, it being used to format React, Jest, immutable-js, Haul, and many more. So you can expect good stability and less bug. You don’t have yo worry that much.

No longer tabs vs space war now. Go ahead, try it yourself..

[Github Project] [Atom Package]
Normalize Your Website CSS

Normalize Your Website CSS

I have been wondering back then when I design a website for serious work for the first time. It seems that website theme out here has a similar design but still maintain its compatibility with many browsers.

And what make me more curious is that when I browse the CSS style on their design, it seems that they are replacing a lot of style from the previously defined style. It makes me curious because why not just change the previous style rather than replace it?

It as if they have some sort of template or something and then they replace it with their own style.

And my question is unanswered for a year until I work for WordPress design later. I never design WordPress theme at this time so I can’t help to learn it from the default theme that comes with WordPress. And then I meet with the answer when reading the CSS that comes with the themes.

CSS themes that come with the WordPress has pretty and well written if I may say. I’m struggling with this since forever. I don’t know how to make CSS file more readable, at least I don’t have any idea how to do that. It gave me an idea on how to write it nicely and now I use the same writing style or structure they use in CSS on WordPress default themes.

Back on topic, it seems that my assumption is pretty much correct. They have some CSS template or some kind of base style. But rather than using them to design itself, it normalizing default style for HTML element so it can have a consistent look on different browsers.

Like button for example, on Chrome default button is pretty much square bit silver gradient background and gray border. On safari, the button has round button with a blue-white gradient on the background. To fix this, you must define more CSS so it looks consistent on both browser like for example by defining button is always has a gray background and darker gray as the border.

To make it more efficient, you can create your own CSS template or collection or normalizer (whatever you want to call it) that act as the default style. If you found any inconsistent HTML style, you can just add it to the template.

Like zoom: 1; fix for example. You use it to fix IE zoom bug. It general and common fix and mostly you will write it on all of your website design anyway. With CSS template, you don’t have to write it again and again. Think of it as default style to make the HTML style consistent across the browsers but you can replace it with your own CSS.

Maybe some of your website design still need to be fixed individually even if you have CSS template. At least you don’t need to do the work you have done many times like fixing IE zoom bug.

There is one problem tough. To have many collections of fixes like that you need many experiences on website design and many hours to write the collection. There is some alternative by using CSS that made by other people such as framework like bootstrap or some of your choice.

No matter what you choose, I think it better for you to use collection from what people make and share rather than define your own. It will save plenty of your time.

CSS Framework

You can choose anything you like. If I have to use the CSS framework then I will recommend to use bootstrap since they are pretty much provide many style for you.

bootstrap

I personally don’t really like CSS framework. They are hard to change since they modify the default style too much. It so much works to completely change CSS framework style.

If you don’t plan to define your own style or modify it too much, then I suggest you use the CSS framework rather than making your own. It doesn’t require much work but you got a nice and consistent design.

The downside is, your final design may not really too far or too different from the CSS framework you use. Basically, the Look & Feel will pretty much give away that your design is using some kind if template. And the size of your CSS size is big since there are styles in the framework you don’t use.

Or if you want to define your own style but only want to have a consistent look on default style then you may use the next solution.

CSS Normalize

I prefer this solution and always use it. It will normalize the default HTML element style and make it consistent across the browser but don’t change it too much. It just fixes inconsistency look on a different browser by defining default style in the CSS. With this, you can define your own CSS after the normalize one.

So even if I use this CSS normalize, it won’t feel like I use some sort of framework or parent theme as my base CSS style. It requires more work since it will only define the default element style but at least you don’t have to define your own fixes like IE zoom bug for example. And it size is relatively quite small since it will only define default CSS style.

You can download Normalize CSS or define your own normalizer. Either way put it on your CSS as the first and default style and then you can define your own style after it.

css normalize nicolas

If you choose to download it, it supports most major browser like Chrome, Firefox, Opera, Safari6+, IE8+, etc. You can read it more on their website and it seems that many companies have been using it as their website CSS base. So I think it worth to check it out.

That it for now, if you have any question or suggestion you can write it in the comment bellow. Thanks for reading!

 

htaccess for Friendly URL on Web

htaccess for Friendly URL on Web

Have you ever wonder how to change your website URL to be more friendly and pretty one? Like for example, you can see at this site, I use URL like this:

http://www.hernantas.com/2016/05/page-name

Rather than

http://www.hernantas.com/?p=123

I’m sure the first one is friendlier and prettier than the second one.

But the question is, how do I do that? Not for the WordPress one, but for general one like the website you created by yourself.

Normally, when you write URL like this:

http://www.hernantas.com/subdir/subdir2

Your server will access subdirectory subdir/subdir2 from your root server directory. So if you want to use friendly URL, you must write index.php file in each directory you can handle. This isn’t possible in practical use and inconvenient. With .htaccess or server configuration, you don’t need to write it in each subdirectory instead, just write one in the root directory and it will handle all of the user URLs.

There is couple way to do this, but I will use the .htaccess one since it simple and don’t modify server configuration.

Requirements

First, you must have a Web server. (Duh)

Not joking. I have been asked by people who think that website exists just with HTML, CSS, image, and JS. Well, that actually quite true, though. Since the server-side script is just generating that type of file so it can feel like dynamic site rather than static.

I’m sure you already know this but make sure that you have a Web server and it is running correctly and smoothly. And make sure your Web server has to allow override or .htaccess will be ignored. You can see how to do that on apache site.

So, How to do That?

First, open your website directory. In the website directory, create a new file called .htaccess. Edit that file and copy the script bellow to your new .htaccess file.

The first line of the script above is to enable rewriting configuration file. We need to do this since we want to rewrite rule on server configuration so we can redirect any requested URL to the single file.

The second line one is the condition of the rule we will make. It will rewrite the URL except for the file or directory is written in the condition.

The third one will rewrite server rule that any requested URI will be handled by index.php file. With this configuration override, URL like this:

http://www.hernantas.com/subdir/subdir2

Will be translated to:

http://www.hernantas.com/index.php/subdir/subdir2

But don’t worry, it won’t change anything on the user browser. It will only affect the server. I’m sure it is simple enough and don’t really need too much works.

That it for now, if you have any further question or suggestion you can write it on the comment bellow. Thank for reading!

Twitch Problems, As Viewer

Twitch Problems, As Viewer

I have been using Twitch quite frequently in the last couple month. It’s quite different from Youtube because what you watch is real-time action with a delay for seconds or minutes.  That mean any mistake made in the live stream can’t be undone or edited. But hey, that what make it different from Youtube. You can enjoy the real-time interaction between streamer and the viewer in real-time. And I found that it’s quite enjoyable.

twitch-home

In this post, I won’t write on how great twitch is or its strength compared to the other site similar site. Rather, I want to discuss any problem I discover when using it. Just like any other great product out here, Twitch has some issue and always will, but not something too serious, just inconvenient. And I will discuss that in this post.

Before we begin, I must warn you that this isn’t some hate post about Twitch or something like that. Just my analysis for the Twitch and what can be improved to increase user experience to the Twitch user. Not all of the issue I write in this post has a solution, at least for now.

So, with that in mind, let’s get started.

Chat Move Too Fast

Chat in Twitch channel, especially the popular one is too fast to follow. The more popular the channel is, the faster chat moving. People like me, who like to follow the conversation and enjoy streamer and viewer interaction, can’t keep up and enjoy that kind of thing. Mostly, the viewer just spams the chat and streamer just quick-filter and ignore most of the chat.

Not that it’s streamer or Twitch or viewer fault . It just the weakness from live streaming. I don’t think there is an easy way to fix this so I doubt it will be addressed anytime soon.

In a nonreal-time video like in the Youtube, comments can be ordered by top comment or newest. This is good since we can just get smaller comments to read, even tough some top comment usually contain hate or flame or spam comment. I know it’s not perfect, at least it a solution and it can be improved.

But Twitch chat? I don’t think you can fix this with the same way you fix offline content like on Youtube.

Boring Ads, Its Too Few

Ads or Advertisements especially the video one is pretty annoying. They disturb the viewer when watching the video. It’s fine if it in the beginning, but when it in the middle of the video, you can get interrupted. Just like TV.

I hate ads and don’t want to watch any ads. But it not like I don’t understand why they put ads and blame or dislike them for that. It just I personally don’t really enjoy watching with ads in it. That why even if I hate it I don’t use Adblock to block them. Well, I still use them for annoying and disturbing or shady ads, but mostly I don’t use them at all.

But the ads in twitch is too few. Sometimes I can watch the same ads 5 times in a row. This is, of course, bad for the user. It will make the user think the ads played too often. Even if you play them every 2 hours, users can become really aware of them if they meet the same ads too often. Heck, I’m sure they remember and can say all the word that said in the ads.

No Old Stream?

Twitch removed the stream that more than 2 weeks old by default unless the streamer set the video to be highlighted. I don’t know if this is because they can’t store that much video or because they think twitch is more like live video streaming rather than like video streaming like youtube so it’s fine to remove very old videos.

Either way, for a user like me, who watch a video so much that it become my TV rather than actual TV and want to watch the older video since the streamer I watch don’t stream that long. At least not as long as I play the stream.

I don’t blame them since they have a life too, but I want to watch more. So I watch their old video to compensate that. But I can’t since Twitch remove the video that more than 2 weeks.

This is not experience breaking, but it would be nice if they don’t remove them. I’m sure I’m not the only one who do this.

Buffering Problem

This one of the thing I found really weird. I have a decent internet connection, not too good but good enough to be able to stream video without any hiccup. But I still have a problem with Twitch.

I don’t know why but high or source quality is not available for me because it always buffering. FYI, Twitch High resolution is only at 720p. I can play 2K videos without any problem on Youtube.

I have an idea why this happen but I’m not too sure since I don’t really test it with a proper test. But I think that the problem is not about the internet speed, rather than internet latency. By latency, I mean that how long it takes from my computer to sent request to receive the response from the server.

How do I know this? I tried to increase my buffer size when streaming and this problem has gone completely. No buffer, no hiccup. Just smooth stream video. If my internet speed is the problem, even if I increase buffer size there is no way it won’t buffer since it can’t keep up with the video. But if I increase buffer and it can be fixed, then there is something in the

But if I increase the buffer size and it is fixed, then there is something in the stream process that makes downloading slower or don’t have enough time to download it. The only thing that comes to my mind is response speed.

I don’t know if this true or not, but this issue really exists

Heavy CPU Usage

I only realize this problem recently since I think that nowadays every render thing like image, video, or animation use hardware acceleration to increase their performance. Surprisingly, Twitch didn’t use hardware acceleration, at least not for the core process like rendering.

How do I know? See this CPU usage in my PC.

twitchUse

Almost 50% for a single video? I don’t believe it will use this much resource to render the video unless they don’t use hardware acceleration.

I have been making my own video player back when I was in high school for fun and I know how heavy it is to play high-quality video. But then I improve them when in college to use hardware acceleration rather than a normal render. The result  is pretty much I can say it doesn’t really use CPU resource. It still does of course, but it so small that it not that noticeable.

As far as I know, Twitch is using flash for playing it videos. But I think that Flash is using hardware acceleration to render so I don’t think this is Flash issue.

According to this Reddit post, there is 2 class you can use in Flash to render video. “Video” and “StageVideo” class. Class “Video” one is too complex to be fully optimized using hardware acceleration. It can but not all. “StageVideo” can and mostly guaranteed to be hardware accelerated. I don’t know why, but it seems that Twitch choose it better to use “Video” rather than “StageVideo”.

This way, the only way for it to be fixed is using a different client to stream to twitch site like livestreamer, or wait for Twitch to fix it.

I think this is all the problem I find and encounter while using Twitch. Once again, this post is not some hate post or critic post to blame or something, just some kind of analysis on Twitch.

If you have any further question or suggestion, you can write it in the comment section bellow. Thank you for reading.

Create Clean Branch in Git

Create Clean Branch in Git

Normally, whenever you create a new branch, you need the original branch and then you branch them. The problem is, they have a parent branch. The commit history from the original branch will be carried to your new branch too. This is intentional and not the git issue. That how git branch supposed to be work.

SourceTree new Branch

Normally, you don’t need to create a completely new branch. Rather, you create a new repository. It new project anyway, so it best to use a different repository. Or maybe just change it gradually.

But, sometimes you need or want to create a completely new branch without any parent but still in the same repository. For whatever your reason is.

You may don’t know this yet, but git has a command to checkout new branch without any parent. It called the orphan branch. With this command, you can create a completly new branch and its root won’t have any connection to the other branch. But it will still have previous files in the repository directory. Don’t worry about that, you can remove it later after the checkout process is done.

So in short, what you want to do is to create a new orphan branch, clear the file and remove file history and then add the new file for your new project. Here is how to do it.

First, create a new orphan branch. It has the same command as git checkout but with the --orphan parameter.

git checkout --orphan <newbranch>

Second, you want to remove any old file in the repository directory. Either you delete it using file explorer, command or by any method you prefer. If you are using git rm command, it may look like this.

git rm --cached -r .

Dot “.” character at the end of the command is intentional. That mean it will remove any files from the current directory which is your repository directory. -r parameter mean is it will remove recursively to ensure any files is deleted.

And that it. Simple right?

If you have any further question or suggestion, you can ask me in the comment bellow. Thank you for reading!

Some Youtube Annoyance

Some Youtube Annoyance

Youtube, the biggest video sharing website. Well, no need for me to explain. I’m sure you know about it.

I’m sure you enjoying watching video on youtube as it is, but I feel like it can improve a bit more. I’m using Youtube heavily, especially when I’m working. I don’t know why, but when I’m working, I feel more productive when I play some videos on my second screen. Even if I just listen to it.

Youtube_Home

Some important thing you must know before reading this post further. I don’t have any intention to do some bad mouthing or judge them or something like that, only discuss what Youtube can improve. Just a small minor detail that can be added without changing it too much. And I think it worth to discuss since they may be overlooked and small, but may can improve user friendliness.

So, without further ado, let’s start…

Reverse playlist

I wonder why, but they didn’t make this feature. Since they have playlist feature, why not make reverse order feature with it.

I’m not talking about playlist owner. I know playlist owner can change the order of the playlist via playlist settings like by date, by popularity, etc. I’m talking about in the normal user that play that created playlist.

For example, when you open some playlist, there are buttons to “play all”, “share”, and “save”. Why not add some more like “Play In Reverse” or “Play From Older to Newest” or something like that.

Youtube Live, Where Are You?

I know, just like Twitch, you can do livestreaming on Youtube. But suprisingly, many people don’t even know youtube can do that. At least according to people I know.

I know since I watch Youtube a lot and read the news about it. But it doesn’t get that much exposure on Youtube.

Look at twitch for a moment. What did you see?

Twitch_Home

You will see some featured channels that are live streaming at the moment or some featured games on the front page.

I didn’t mean they should copy or imitate Twitch. Twitch is video live streaming website and they offer live streaming as the main feature. They want to expose that main feature as much as possible, they want people to know about it. So, when people visit their website, people can tell that their website is some (gaming?) video live stream website.

Youtube is  video sharing website and that the main feature of Youtube. Of course, they want to expose that feature on the front page. And I think they do pretty good job doing that.

But what I mean is if you have some feature that people want to use often and know, don’t hide it. If people don’t know about some feature, it same as if it doesn’t exist in the first place.

If you need to open 2 page or more before you can reach the feature you want, I consider them as the second feature where users don’t really use it frequently. Like privacy settings for example or copyright claim. Most people don’t use that feature, maybe once or twice but not always. So they can be put on the second page like settings for example.

But live channel? I think you want to put that in front or expose them in the main page.

One of the reason is, they are live video. Whatever they are doing, they do it now (maybe with some delay). It has limited time to watch. If you miss it, even if you can play it after it ended, you may can’t get the same feeling as watching it live.

Second, at least you want to tell people that Youtube can be used to stream some live video.

This may need to do some major change to Youtube. But I think it worth to mention since Youtube already has this live stream feature and since it didn’t really well know, they need to tell the user more about it.

Default Resolution

Youtube can support many video resolution, be it high resolution like 2K or 1K resolution or smaller resolution like 480p or 320p. And it can be set automatically depend on your internet speed.

But here is one problem, there is no option to set default resolution.

Why is this a problem? Sometimes, when you play some video on the youtube, it fails to detect my internet speed connection and set it to low resolution. I can play 2K resolution without a problem. I don’t why this happen, though.

I don’t think there is an easy fix for this. Since when you load the page it may need all of the bandwidth. So it will put heavy traffic to my connection and fail to detect my actual speed. But at least they can let me set the default resolution for it. It may make the video loading slow at first when the page is still being loaded but at least I rather wait for 5 seconds for a video to load rather than watch it in lower resolution. I think, it not just me that feel this way.

Conclusion

I’m sure there are more feature people, some of them may need to change a lot of thing. But I think this kind of feature I write in this post can be added without too much change or work.

Well, some of them can be fixed with plugin though…

I’m sure there is more I can add but for now, I think this is small and the most important thing they can do to improve Youtube without doing too much change or work.

If you have any idea, question, feedback or request what to post next, you can write it in the comment bellow. Don’t worry, it all free. Thanks for reading.

Avoiding SQL Injection in PHP

Avoiding SQL Injection in PHP

Recently, I’m reviewing some web project that made using PHP. It nice website, responsive and can support both PC and mobile display. But, it seems that they didn’t keep security in mind when they develop that website.

By security, I didn’t mean that unauthorized people can access certain login-only page or something. But it seems that they still trust user input naively.

Of course, they still have some sort of validation, but it only work on username or password. I still can do some SQL injection as long as it wasn’t username and password. I can input thing like this:

And when I asked if they know that their website has this kind of vulnerability, they said they don’t know. Security is overrated huh.

But I’m amazed that they didn’t have any security issue to this day. I guess they are quite lucky.

So, how we avoid this kind of problem? I know some ways to fix this kind of issue, and they are pretty much easy to do.

Avoid Using SQL Special Char

This makes sense since the cause of this kind of issue is because user input contain SQL special char and it makes your SQL syntax bugged. You can use any validation to only allow some character to be passed like alphabet or number only. Maybe with some kind of regex validation like this:

The code above will only allow the username to be an alphabet, number, underscore or hyphen and must in 5 to 16 character length.

I think that this is what I do when I started doing web programming 7 years ago. I naturally thought that to avoid this, I just need the user to not input those problematic characters.

But even if I tell you can avoid SQL injection using this kind of method, I won’t recommend it for you to rely on it. Sometimes, you can’t really avoid inserting this special character to your database.

It’s better to use the next solution.

Using Mysql Escape String

One of the fixes you can do is using mysql_escape_string or mysql_real_escape_string, or similar function on MySqli. As far as I know, this is the most common and most known way to avoiding SQL Injection. This will let you avoiding SQL special character like apostrophe (‘) and quotation (“) mark and you can use it like this:

Now you can avoid any kind of SQL special character in your SQL syntax. The downfall using this code is that you need connection to your database server first. This can be inconvenient if you are using this method before you have connection to your database server. I have this code snippet to mimic how

I have this code snippet to mimic how mysql_real_escape_string work and avoiding special character and you can use it on your project if you want:

You can make this as global function or static method or whatever method you prefer.

There is some important thing you should know, in the previous version of PHP I don’t know which version. There is a bug in mysql_real_escape_string escape routine and it become unreliable to escaping SQL special characters.

So I recommend you using the next method for avoiding SQL Injection.

Use SQL Binding

This one is my most recommend method to avoiding any issue like SQL injection. By using SQL Binding like mysqli_stmt_bind_param, rather than replacing, escaping and securing the input string, it let you bind your input to be passed when using mysqli_prepare. And it not really that complicated too, look at the code bellow:

You just need to prepare your SQL syntax statement using mysqli_prepare and then bind them to your input variable using mysqli_stmt_bind_param.

If you use any kind of class to warp database function, you may find this method to be unimplemented because mysqli_stmt_bind_param accept dynamic number arguments but you can’t really create a method that accepts dynamic number arguments.

Fortunately, there is some kind of workaround using ReflectionClass`. which you can do it like this example code:

With the code above, you can pass many arguments with an array. You just need to define your arguments order as if they are an array, and pass it using invokeArgs.

I think that all you need to know about how to secure your website from SQL injection. One tips I want to give is that don’t trust any kind of input that inputed by the user. You don’t want to learn this the hard way.

If you have any question or feedback, feel free to write them in the comment bellow. Don’t worry, it’s free. Thank you for reading.

Generate Your PHP Documentation

Generate Your PHP Documentation

In my last post, I tell you to make your code well documented, for a reason. But sometimes, making your code documented wasn’t that much help at all.

I mean, to know what your code docs, you need at least code hinting that shows docs like IntelliSense, or you must open the source code. Of course, this can be inconvenient. Especially if your IDE/Editor doesn’t have that feature at all.

In a language like PHP, it seems that I can’t find proper/perfect code hinting that can be as good as IntelliSense for C# or C++. It not something that can’t be tolerated since it will be hard to know data type in variable especially a programming language like PHP. Look at the code bellow:

This code is for loading the class file and return the instance of that class. But in general, the variable $router can hold any value, like boolean, int, float or hold nothing (null).

You, the programmer may know what the data type is, but your computer can’t really know it at least until you run the code. Because of that, it will be hard to show code hint like method or property on $router var.

That why it better to get used to reading the documentation. It doesn’t have to be reading the docs on the source code, just look at any web documentation if available. It more friendly and easy to navigate. Look at this Amazon Web Service SDK.

You don’t have to make it manually, you can generate that. As long as your documentation is written correctly, you can generate your code docs easily.

You can use any docs generator you like, but in this post, I will show you an example how to generate docs using ApiGen. Don’t worry, it pretty easy.

apigen_website

Requirements

First thing first. You need any requirements and know how to run PHAR file. If you don’t know how you can read my other post on how to run .phar files.

You can also install it using composer, but I think the easiest way to do this is using the .phar version. That why, we will be using the .phar version.

Installation

You must download the ApiGen .phar file and can be downloaded from its github repository. If you feel lazy to search for it, you can click here. It will redirect you to ApiGen github repository download section. Download the .phar file and place it anywhere you like.

Running ApiGen

Now after you get the ApiGen .phar file, just run it with parameter generate with a path to your PHP project directory and output. Like this:

Parameter -s mean that you define the source directory where your code is and -d mean that you define the output directory.

If you want to get all parameter command you can do with ApiGen, you can enter CLI command like this:

To ease the process, you can create the .bat file if you are on windows or bash script if you are on Linux. I use this to generate PHP Docs using ApiGen and I just need to insert the path to my source code and docs title, like this:

Simple right? And the .bat file I’m using look like this:

You can copy my .bat source code if you want and use it whatever you want, it nothing special.

That it for now, thank you for reading. If you have any question or feedback, feel free to write them in the comment bellow. Don’t worry, it’s free.

Make Your Code Documented People

Make Your Code Documented People

In the last couple years, while working on collaborations projects with some companies. Working with different frameworks, people, database, and APIs.

I notice several thing that doesn’t really suit me and I consider them as ineffective or bad practice. One of them is documentation.

DocCode
PHP Documentation

Some people I work with (not all), consider it as a waste of time, no one will read it. Well, it does make sense. Just like the user manual, no one bothers to read it.

But one thing I want you, who think like this, to know this one thing.

It not just for other people. It for you too.

Even if you work on a personal project, where you just work alone. Documentation can still be useful.

Yeah, you may know inside your code well. But how long you can say the same thing? 1 month? 3 month? 1 year?

I have several personal project and most of them are more than 4 years old. I develop them when I still in high school and still maintain some of them that I still have an interest in.

And, I can say for sure. I don’t remember my own code, application flow, or architecture I use on the project. Heck, I can’t even remember the project that I did 1 month ago.

Unfortunately for us (or maybe fortunate?), our memory is limited. We can forget things. Even things that we didn’t want to forget.

Documentation can help you remember. They can act like a note for you. It may useless for other people, but it can be useful for you.

I didn’t recognize the importance of the documentation until I enter college and got more busy. And when I open my own personal project after not open it after a while, maybe like 2 or 3 months. I feel alienated. I don’t know how to modify this or that in my own project.

This may sound funny, but it can be pretty painful because you must learn it again by reading the code you make.

You are lucky if your code is easy, you can re-learn it pretty fast. If it complex one, well, it may feel like it better to make it from scratch.

Maybe in the future, it will be open source project.

I have several personal project that I make when I was in high school. And when I work on them, I didn’t even think that my project will be developed with other people.

I just make them for fun. Seriously.

Unexpectedly, it did happen. Some people think that my project is a bit interesting, and want to expand it even further.

But then I remembered that my project didn’t have documentation. I can teach them directly, face to face. But they can’t learn it or explore it without my help. Maybe they can but it will be hard.

I mean, reading your own code that has been forgotten is a bit painful. Read other people without documentation is like exploring and make a map for a maze.

Conclusion

I hope that with this post, you can understand how important documentation is.

If you are in a rush because of deadline or something. Create note in the documentation place. Like this for example:

And you can search and create it later after the deadline. At least, that what I do.

Thank you for reading. If you have any question or feedback, you can write them in the comment bellow. Have a good day!