Merge pull request #9 from urls-framework/v2.0.1

V2.0.1
urls-framework · Oct 18, 2022 · fe048bf · fe048bf
2 parents 9e8bf9f + b521177
commit fe048bf
Show file tree

Hide file tree

Showing 34 changed files with 1,245 additions and 23 deletions.
diff --git a/docs/classes/methods/path.md b/docs/classes/methods/path.md
@@ -12,7 +12,7 @@ Creates a new path.
 |   $file   | -       | String/Array/Object: Urls | :heavy_check_mark: | The file path and name you want to use as a template or an array containing one string element you want to directly output or a Urls object to compare a sub-path. |
 |   $end    | False   | Bool   | :x:                | True if this is the end of the path. If there is more after this point, it will be seen as not matching and will result in a 404 error. |
 |   $cs     | NULL    | Bool   | :x:                | Whether this path is case sensitive or not. If NULL, the default defined in `URLS::$cs` will be assumed. |
-|   $vars   | NULL    | Array  | :x:                | An array of variables to pass on to the included page. |
+|   $vars   | NULL    | All    | :x:                | A variable to pass on to the included page. The variable is added to the end of the array `Urls::$vars`. |
 ## Examples
 ```PHP
 <?php
@@ -29,7 +29,7 @@ $blog = new Urls;
 $urls->path('posts/', 'posts.php', true, false);
 
 $urls = new Urls;
-$urls->path('blog/', 'blog-home.php', true, false, array("Hello, ", "World!"));
+$urls->path('blog/', 'blog-home.php', true, false, "Hello, World!");
 $urls->path('blog/', ["This is my blog!"], true, false);
 $urls->path('blog/', Urls::echo("This is my blog!"), true, false);
 $urls->path('blog/', $blog, false, false); // Note: $end should always be false if $file is type object or else, $blog will not be called

diff --git a/guides/MANUAL_INSTALL.md b/guides/MANUAL_INSTALL.md
@@ -12,7 +12,7 @@
    ?>
    ```
 3. Create a `.htaccess` file in the base directory and fill it with the following (fill in the blanks):
-   ```
+   ```ApacheConf
    # --URLS BEGIN--
    # The following lines between \"--URLS BEGIN--\" and \"--URLS END--\" are
    # automatically generated by the URLS framework. These lines should
@@ -23,14 +23,15 @@
    RewriteRule ^(the name of your settings file regex encoded)$ - [L]
    # --URLS ADD_COND BEGIN--
    # --URLS ADD_COND END--
-   RewriteCond %{REQUEST_FILENAME} !-f
-   RewriteCond %{REQUEST_FILENAME} !-d
+   RewriteCond %{REQUEST_FILENAME} !-d [OR]
+   RewriteCond %{REQUEST_FILENAME} !-f [OR]
+   RewriteCond %{REQUEST_FILENAME} \.php$
    RewriteRule . (the name of your settings file regex encoded) [L]
    RewriteRule ^$ (the base directory followed by the settings file name) [L]
    # --URLS END--
    ```
    Here is a complete example:
-   ```
+   ```ApacheConf
    # --URLS BEGIN--
    # The following lines between "--URLS BEGIN--" and "--URLS END--" are
    # automatically generated by the URLS framework. These lines should
@@ -42,8 +43,9 @@
    RewriteRule ^settings\.php$ - [L]
    # --URLS ADD_COND BEGIN--
    # --URLS ADD_COND END--
-   RewriteCond %{REQUEST_FILENAME} !-f
-   RewriteCond %{REQUEST_FILENAME} !-d
+   RewriteCond %{REQUEST_FILENAME} !-d [OR]
+   RewriteCond %{REQUEST_FILENAME} !-f [OR]
+   RewriteCond %{REQUEST_FILENAME} \.php$
    RewriteRule . /blog/setting.php [L]
    RewriteRule ^$ /blog/settings.php [L]
    # --URLS END--

diff --git a/guides/tutorial/COMPLETE_TUTORIAL.md b/guides/tutorial/COMPLETE_TUTORIAL.md
@@ -12,5 +12,56 @@ This guide will walk you through a complete implementaion of URLS. You will be m
 2. [Getting Started with URLS](getting_started.md)
 3. [Templates](templates.md)
 4. [Static Files](static_files.md)
+5. [More Pages](pages.md)
+6. [Nesting Pages (part 1)](nesting_p1.md)
+7. [Nesting Pages (part 2)](nesting_p2.md)
+8. [Nesting Pages (part 3)](nesting_p3.md)
+9. [Variable Paths](variable.md)
+10. [HTTP Errors (part 1)](errors_p1.md)
+11. [HTTP Errors (part 2)](errors_p2.md)
+12. [HTTP Errors (part 3)](errors_p3.md)
+13. [Case Sensitivity](cs.md)
+14. [Redirects](redirects.md)
+15. [Passing Variables](vars.md)
+16. [Deploying](deploy.md)
+17. [Conclusion](conclusion.md)
+
+## Project Structure
+```
+└── (base directory)/
+    ├── errors/
+    │   ├── 404.php
+    │   ├── 500.php
+    │   └── contributors_500.php
+    ├── includes/
+    │   ├── footer.inc.php
+    │   └── header.inc.php
+    ├── static/
+    │   └── style.css
+    ├── templates/
+    │   ├── about.php
+    │   ├── Another-Friend.php
+    │   ├── authors.php
+    │   ├── contributors.php
+    │   ├── errors.php
+    │   ├── home.php
+    │   ├── Me.php
+    │   ├── My-Friend.php
+    │   ├── posts.php
+    │   └── vars.php
+    ├── urls/
+    │   ├── LICENSE
+    │   ├── update.php
+    │   └── Urls.php
+    ├── .htaccess
+    ├── author_settings.php
+    └── settings.php
+```
+## Project Images
+|<picture><img alt="Output" src="assets/home_tutorial.png"></picture>|<picture><img alt="Output" src="assets/about_page.png"></picture>|
+|--------------------------------------------------------------------|--------------------------------------------------------------------|
+|<picture><img alt="Output" src="assets/posts_tutorial.png"></picture>|<picture><img alt="Output" src="assets/post_1_tutorial.png"></picture>|
+|<picture><img alt="Output" src="assets/authors_tutorial.png"></picture>|<picture><img alt="Output" src="assets/404.png"></picture>|
+
 ___
 [Next: Project Setup](setup.md)
diff --git a/guides/tutorial/assets/404.png b/guides/tutorial/assets/404.png
diff --git a/guides/tutorial/assets/about_page.png b/guides/tutorial/assets/about_page.png
diff --git a/guides/tutorial/assets/authors_tutorial.png b/guides/tutorial/assets/authors_tutorial.png
diff --git a/guides/tutorial/assets/contributors_404.png b/guides/tutorial/assets/contributors_404.png
diff --git a/guides/tutorial/assets/home_tutorial.png b/guides/tutorial/assets/home_tutorial.png
diff --git a/guides/tutorial/assets/p5_404.png b/guides/tutorial/assets/p5_404.png
diff --git a/guides/tutorial/assets/post_1_tutorial.png b/guides/tutorial/assets/post_1_tutorial.png
diff --git a/guides/tutorial/assets/posts_tutorial.png b/guides/tutorial/assets/posts_tutorial.png
diff --git a/guides/tutorial/assets/vars.png b/guides/tutorial/assets/vars.png
diff --git a/guides/tutorial/conclusion.md b/guides/tutorial/conclusion.md
@@ -0,0 +1,36 @@
+# Conclusion
+This is finally the end of this tutorial. You should now have a solid understanding of the URLS Framework. The complete project files for this tutorial can be found [here](/guides/tutorial/files). The final project structure should look like:
+```
+└── (base directory)/
+    ├── errors/
+    │   ├── 404.php
+    │   ├── 500.php
+    │   └── contributors_500.php
+    ├── includes/
+    │   ├── footer.inc.php
+    │   └── header.inc.php
+    ├── static/
+    │   └── style.css
+    ├── templates/
+    │   ├── about.php
+    │   ├── Another-Friend.php
+    │   ├── authors.php
+    │   ├── contributors.php
+    │   ├── errors.php
+    │   ├── home.php
+    │   ├── Me.php
+    │   ├── My-Friend.php
+    │   ├── posts.php
+    │   └── vars.php
+    ├── urls/
+    │   ├── LICENSE
+    │   ├── update.php
+    │   └── Urls.php
+    ├── .htaccess
+    ├── author_settings.php
+    └── settings.php
+```
+While this tutorial covered most topics, there is still a lot to learn about URLS. Now that you've completed this tutorial, the best way to learn more is to visit the [documentation](/DOCS.md).  
+Happy coding! :)
+___
+[Previous: Deploying](deploy.md)  
diff --git a/guides/tutorial/cs.md b/guides/tutorial/cs.md
@@ -0,0 +1,79 @@
+# Case Sensitivity
+By default, URLS is case sensitive. However, there may be times where you don't want a path or even the project to be case sensitive. This section will cover how to make something not case sensitive.
+## Project Level Case Sensitivity
+Project level case sensitivity is the easiest to implement. Typically, you want to make the entire project case sensitive so we are going to keep it case sensitive.
+1. Set `Urls::$cs = true` under `Urls::$defaultErrors` in `settings.php`. The file should now look like:
+   ```PHP
+   <?php
+   /*
+   URLS framework url config file.
+
+   Add your paths here:
+   ex. $urls->path('blog/', 'blog-home.php', true);
+   */
+   include 'urls/Urls.php';
+   Urls::$base = '/';
+   Urls::$defaultErrors[404] = "errors/404.php";
+   Urls::$cs = true;
+
+   $contributors = new Urls;
+   $contributors->errors[404] = "errors/contributors_404.php";
+   $contributors->path('/', 'templates/contributors.php', true);
+   $contributors->path('Me', 'templates/Me.php', true);
+   $contributors->path('My-Friend', 'templates/My-Friend.php', true);
+   $contributors->path('Another-Friend', 'templates/Another-Friend.php', true);
+
+   $urls = new Urls;
+   $urls->path('/', 'templates/home.php', true);
+   $urls->path('about/', 'templates/about.php', true);
+   $urls->path('about/authors/', 'authors_settings.php');
+   $urls->path('about/contributors/', $contributors);
+   $urls->path('posts/', 'templates/posts.php', true);
+   $urls->path('posts/<post>/', 'templates/posts.php', true);
+
+   $urls->exe();
+
+   ?>
+   ```
+2. That's it! If you want to make the project not case sensitive, simpily set `Urls::$cs` to `false`.
+
+## Path Level Case Sensitivity
+Path level Case Sensitivity can be set on all paths and redirects (to be covered later). So far, we have only used three arguments in a path. The fourth argument is a boolean variable that sets the case sensitivity.
+1. Add the path `$urls->path('home/', 'templates/home.php', true, false);` to `$urls` in `settings.php`. The file should now look like:
+   ```PHP
+   <?php
+   /*
+   URLS framework url config file.
+
+   Add your paths here:
+   ex. $urls->path('blog/', 'blog-home.php', true);
+   */
+   include 'urls/Urls.php';
+   Urls::$base = '/';
+   Urls::$defaultErrors[404] = "errors/404.php";
+   Urls::$cs = true;
+
+   $contributors = new Urls;
+   $contributors->errors[404] = "errors/contributors_404.php";
+   $contributors->path('/', 'templates/contributors.php', true);
+   $contributors->path('Me', 'templates/Me.php', true);
+   $contributors->path('My-Friend', 'templates/My-Friend.php', true);
+   $contributors->path('Another-Friend', 'templates/Another-Friend.php', true);
+
+   $urls = new Urls;
+   $urls->path('/', 'templates/home.php', true);
+   $urls->path('about/', 'templates/about.php', true);
+   $urls->path('about/authors/', 'authors_settings.php');
+   $urls->path('about/contributors/', $contributors);
+   $urls->path('posts/', 'templates/posts.php', true);
+   $urls->path('posts/<post>/', 'templates/posts.php', true);
+   $urls->path('home/', 'templates/home.php', true, false);
+
+   $urls->exe();
+
+   ?>
+   ```
+2. Now if you go to a URL like [localhost/HoMe](http://locahlost/HoMe) you should see the home page.
+___
+[Previous: HTTP Errors (part 3)](errors_p3.md)  
+[Next: Redirects](redirects.md)
diff --git a/guides/tutorial/deploy.md b/guides/tutorial/deploy.md
@@ -0,0 +1,86 @@
+# Deploying
+The final step to building our blog is deploying it on a web server. URLS makes it really easy to deploy your site however, there are a few things that need to be changed in order for it to work on a live server.
+1. Make sure that your site is not in debug mode. Debug mode is off by default, however it is a good idea to manually turn it off. To do this, add `Urls::$debug = false` under `Urls::$cs` in `settings.php`. The final file should look like:
+   ```PHP
+   <?php
+   /*
+   URLS framework url config file.
+
+   Add your paths here:
+   ex. $urls->path('blog/', 'blog-home.php', true);
+   */
+   include 'urls/Urls.php';
+   Urls::$base = '/';
+   Urls::$defaultErrors[404] = "errors/404.php";
+   Urls::$cs = true;
+   Urls::$debug = false;
+
+   $contributors = new Urls;
+   $contributors->errors[404] = "errors/contributors_404.php";
+   $contributors->path('/', 'templates/contributors.php', true);
+   $contributors->path('Me', 'templates/Me.php', true);
+   $contributors->path('My-Friend', 'templates/My-Friend.php', true);
+   $contributors->path('Another-Friend', 'templates/Another-Friend.php', true);
+
+   $urls = new Urls;
+   $urls->path('/', 'templates/home.php', true);
+   $urls->path('about/', 'templates/about.php', true);
+   $urls->path('about/authors/', 'authors_settings.php');
+   $urls->path('about/contributors/', $contributors);
+   $urls->path('posts/', 'templates/posts.php', true);
+   $urls->path('posts/<post>/', 'templates/posts.php', true);
+   $urls->path('home/', 'templates/home.php', true, false);
+   $urls->redirect('post1/', Urls::$base.'posts/1');
+   $urls->redirect('URLS/', 'https://github.com/urls-framework/URLS', false, 302);
+   $urls->path('vars/', 'templates/vars.php', true, true, "This is a variable from the path");
+
+   $urls->exe();
+
+   ?>
+   ```
+2. Next, set `Urls::$base` to the project directory you will be deploying to. If you used the public root as your base directory in development and you are deploying to the root directory on your server, then you do not need to change this.
+3. In `.htaccess`, change the `RewriteBase` to your new directory. Then change the path before "settings.php" in `RewriteRule . /urlsblog/settings.php [L]` and `RewriteRule ^$ /urlsblog/settings.php [L]` to your new directory. For example, if your development `.htaccess` is:
+   ```ApacheConf
+   # --URLS BEGIN--
+   # The following lines between "--URLS BEGIN--" and "--URLS END--" are
+   # automatically generated by the URLS framework. These lines should
+   # not be edited as it may result in unwanted behavior of the site. Any
+   # edits made may be overwritten automatically.
+   Options +FollowSymLinks
+   RewriteEngine On
+   RewriteBase /urlsblog/
+   RewriteRule ^settings\.php$ - [L]
+   # --URLS ADD_COND BEGIN--
+   # --URLS ADD_COND END--
+   RewriteCond %{REQUEST_FILENAME} !-d [OR]
+   RewriteCond %{REQUEST_FILENAME} !-f [OR]
+   RewriteCond %{REQUEST_FILENAME} \.php$
+   RewriteRule . /urlsblog/settings.php [L]
+   RewriteRule ^$ /urlsblog/settings.php [L]
+   # --URLS END--
+   ```
+   then your production `.htaccess` would be:
+   ```ApacheConf
+   # --URLS BEGIN--
+   # The following lines between "--URLS BEGIN--" and "--URLS END--" are
+   # automatically generated by the URLS framework. These lines should
+   # not be edited as it may result in unwanted behavior of the site. Any
+   # edits made may be overwritten automatically.
+   Options +FollowSymLinks
+   RewriteEngine On
+   RewriteBase /
+   RewriteRule ^settings\.php$ - [L]
+   # --URLS ADD_COND BEGIN--
+   # --URLS ADD_COND END--
+   RewriteCond %{REQUEST_FILENAME} !-d [OR]
+   RewriteCond %{REQUEST_FILENAME} !-f [OR]
+   RewriteCond %{REQUEST_FILENAME} \.php$
+   RewriteRule . /settings.php [L]
+   RewriteRule ^$ /settings.php [L]
+   # --URLS END--
+   ```
+   if your development directory was `/urlsblog/` and your production directory was the public root. Again, if you used the public root as your base directory in development and you are deploying to the root directory on your server, then you do not need to change this.
+4. Finally, upload your project files to your server. Since each host is different, I cannot show you how to do it. Contact your host to find out how to upload files.
+___
+[Previous: Passing Variables](vars.md)  
+[Next: Conclusion](conclusion.md)
diff --git a/guides/tutorial/errors_p1.md b/guides/tutorial/errors_p1.md
@@ -0,0 +1,64 @@
+# HTTP Errors (part 1)
+In the [last section](variable.md), if a post was not found, then the user would be redirected to [localhost/posts](http://localhost/posts). This is not the best way to handle error. A better way is to call a 404 error. Luckily, URLS helps with that.
+## Calling Errors
+1. In `posts.php` change the if statement right after the `$posts` definition to:
+   ```PHP
+   if (isset(Urls::$access['post'])) {
+       if (isset($posts[Urls::$access['post']])) {
+           $pageTitle = $posts[Urls::$access['post']]['title'];
+       } else {
+           Urls::$self->error_404();
+       }
+   } else {
+       $pageTitle = 'Posts';
+   }
+   ```
+   The file should now look like:
+   ```PHP
+   <?php
+
+   $posts = array(
+       '1'=>array('title'=>'Post One', 'content'=>'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque in scelerisque nibh, et mattis nunc. Aliquam cursus placerat ex in varius. Phasellus urna elit, aliquam nec nulla ac, fringilla blandit justo. Nulla facilisi. Pellentesque non orci non urna venenatis egestas. Quisque gravida mi sed dui fermentum, eu tincidunt elit cursus. Sed lobortis ut turpis quis pretium. Phasellus accumsan tempus commodo. Proin nisi justo, mollis in faucibus ut, mattis a dolor. Ut congue mi tortor, nec pharetra tellus pretium non. Maecenas finibus, sapien in eleifend efficitur, risus magna volutpat sem, nec iaculis risus enim non tellus. Fusce lacinia odio a nibh molestie tincidunt. Aenean nec dui leo.'),
+       '2'=>array('title'=>'Post Two', 'content'=>'Nam mattis lacus id sem vulputate, vel congue nulla consectetur. Sed euismod justo eu urna molestie efficitur. Suspendisse egestas mattis feugiat. Fusce viverra varius sem. Fusce sed sollicitudin ipsum. Sed pulvinar vulputate eros, eget lobortis mi lacinia eget. Nunc egestas id velit id pellentesque. Nam aliquam vestibulum nunc at varius. Donec mauris nisl, pretium ac tempus eget, pulvinar non elit.'),
+       '3'=>array('title'=>'Post Three', 'content'=>'Praesent gravida suscipit hendrerit. Donec in purus hendrerit, mattis quam vel, fermentum odio. Nulla non elit molestie, tincidunt odio at, lacinia magna. Donec id elementum elit. Morbi consectetur urna arcu, dignissim dictum velit vulputate vitae. Integer sed varius lorem, a vestibulum felis. Ut tempor tortor vitae lorem posuere volutpat. Morbi consectetur neque viverra est laoreet, et faucibus turpis sagittis. In sit amet est quis enim euismod euismod. Integer sed nisi malesuada, iaculis ante vel, tempus nisl. Nulla ex risus, facilisis et ullamcorper eget, accumsan at erat. Ut vitae mollis augue, nec bibendum libero. Integer non leo eget risus euismod ornare vitae nec purus. Nam tincidunt aliquet elit.'),
+   );
+
+   if (isset(Urls::$access['post'])) {
+       if (isset($posts[Urls::$access['post']])) {
+           $pageTitle = $posts[Urls::$access['post']]['title'];
+       } else {
+           Urls::$self->error_404();
+       }
+   } else {
+       $pageTitle = 'Posts';
+   }
+
+   include './includes/header.inc.php';
+
+   if (isset(Urls::$access['post']) && isset($posts[Urls::$access['post']])) {
+       ?>
+       <h1><?php echo $posts[Urls::$access['post']]['title']; ?></h1>
+       <p><?php echo $posts[Urls::$access['post']]['content'] ?></p>
+       <?php 
+   } else { 
+       for ($i=0; $i < count($posts); $i++) {
+           ?>
+           <h1><a href="<?php echo Urls::$base.'posts/'.urlencode($i + 1); ?>"><?php echo $posts[strval($i + 1)]['title']; ?></a></h1>
+           <p><?php echo $posts[strval($i + 1)]['content'] ?></p>
+           <?php
+       }
+   }
+
+   ?>
+
+   <?php include './includes/footer.inc.php'; ?>
+   ```
+2. If you try to go to any post that does not exist like [localhost/posts/5](http://localhost/posts/5), you will get a 404 error.
+   <picture>
+       <img alt="Output" src="assets/p5_404.png">
+   </picture>
+## Explanation
+This section has a couple new parts to it, the first one being the `Urls::$self` variable. This variable works like the `$this` variable. It contains the current instance of the `Urls` class. So why wouldn't you just use `$this`? The reason is because `$this` refers to the current object. While `$this` will usually work, if you are working inside another class within your file, `$this` will no longer refer the current `Urls` instance. Instead of `Urls::$self`, we could have used `end(Urls::$objects)`. This variable is an array that holds every instance of the `Urls` class called to get to this point in the order they were visited. There are other errors you can call with URLS. They are `error_404()`, `error_500()`, `error_403()`, `error_400()`, and `error_401()`. If you want to call any other errors, you have to use the `error()` function. See [error()](/docs/classes/methods/error.md) in the [documentation](/DOCS.md) for more information.
+___
+[Previous: Variable Paths](variable.md)  
+[Next: HTTP Errors (part 2)](errors_p2.md)