README

# Shani Web Application Framework

Shani 是一个开源的Web框架，旨在通过最小努力实现快速应用程序开发，同时性能、安全性、创造性和现代Web应用程序开发实践共存。

用例

使用 Shani 来构建客户端或服务器端应用程序。您也可以在 Shani 站在后端的同时使用您最喜欢的前端框架，反之亦然。

主要功能

可扩展性
健壮（错误容错性）
安全（CSRF、会话管理、认证和授权）
快速
多进程
多线程
事件驱动
非阻塞
HMVC
零依赖
动态路由
内置Web服务器
WebSocket支持
状态管理
第三方库支持
最佳实践API支持
支持JSON、XML、YAML、CSV和HTML
负载均衡（轮询、抢占、固定）
内存管理
异步

系统要求

Shani 在Linux和Mac OS上运行良好，但是Windows用户可以使用Windows Subsystem for Linux（WSL）。

安装

无需安装。

使用

要启动 Shani 应用程序Web服务器，请在终端运行以下命令

$ php index.php

1.0 项目结构

Shani应用程序具有以下项目结构

/root
	apps/ (Contains user applications. Create your applications here)
	config/ (Contains important server and hosts configurations)
		hosts/ (Contains host configurations files (hostname.yml). Register your application here)
			localhost.yml (can be customized)
		ssl/ (Contains server ssl certificate files for)
		mime.yml
		server.yml (Server configuration are written here, and can be customized.)
	gui/ (Contains support for GUI building)
		assets/ (Contains static files e.g: .css, .js,fonts etc shared by all applications)
		html/ (Contains html templates comes with framework)
	library/ (Contains files comes with framework that can be used directly by user application)
	shani/ (Contains core framework files)
	index.php (The entry point of a Shani application)

1.0.1 用户应用程序结构

一个典型的用户应用程序文件夹结构可能如下所示

apps/
	demo/
		v1/
			modules/ (Can be renamed)
				module1_name/ (Can be desired module name)
					src/ (Can be renamed)
						get/ (This is the request method as directory)
							Resource.php (Can be any resource file)
					views/ (can be renamed)
						resource/ (All lowercase, must match resource file name)
					lang/ (Can be renamed)
						resource/ (All lowercase, must match resource file name)
					breadcrumb/(Can be renamed)
						resource/ (All lowercase, must match resource file name)
							functions/ (can be renamed)
								function-name.php (Must match function name in resource file class)
							resource.php (must match module name)
						module1_name.php (must match module name)

假设我们想创建一个名为 demo 的应用程序，版本为1.0（v1）。我们的应用程序有一个名为 greetings 的模块和一个名为 Hello.php 的资源文件。

现在，看看以下资源文件的示例

<?php

namespace apps\demo\v1\modules\greetings\web\get {

	use shani\engine\http\App;

    final class Hello
    {
        private App $app;

        public function __construct(App &$app)
        {
            $this->app = $app;
        }

        /**
         * Display greetings from Shani.
         */
        public function world()
        {
	        //sending output to user agent using default view file (world.php)
            $this->app->render();
        }
    }
}

创建视图文件：（apps/demo/v1/modules/greetings/views/hello/world.php）

<h1>Hello From Shani</h1>

考虑到上面的例子，我们的应用程序文件夹结构将是这样的

apps/
    demo/
        v1/
            modules/
                greetings/
                    src/
                        get/
                            Hello.php
                    views/
                        hello/
                            world.php

1.0.2 注册应用程序

下一步是注册我们的应用程序，使其可在网络上使用。您可以通过转到 /config/hosts/ 并创建一个名为 localhost.yml 的配置文件来完成此操作。您可以选择任何名称。

注意！ 每个应用程序都必须有它自己的配置文件

以下是与 Shani 一起提供的默认应用程序配置

# A user application must have atleast one version.
VERSIONS:
  "1.0":
    # Environment variables are customs, you can create any e.g DEV, TEST, PROD or any
    # Must extends shani\advisors\Configuration
    ENVIRONMENTS:
      DEV: \apps\demo\v1\config\Settings
      # Active environment can any one of the provided above.
    ACTIVE_ENVIRONMENT: DEV
    DEFAULT_LANGUAGE: sw
    # Whether an application is running or not
    RUNNING: true
  "2.0":
    ENVIRONMENTS:
      DEV: \apps\demo\v2\config\Settings
    ACTIVE_ENVIRONMENT: DEV
    DEFAULT_LANGUAGE: sw
    RUNNING: true
# The default application version
DEFAULT_VERSION: "2.0"

让我们根据我们的应用程序需求自定义此文件

VERSIONS:
  "1.0":
    ENVIRONMENTS:
      DEV: \apps\demo\v1\config\DevSettings
      TEST: \apps\demo\v1\config\TestSettings
      PROD: \apps\demo\v1\config\ProdSettings
    ACTIVE_ENVIRONMENT: DEV
    DEFAULT_LANGUAGE: sw
    RUNNING: true
DEFAULT_VERSION: "1.0"

下一步是创建这些配置类文件。我们将在 apps/demo/v1/config/ 下创建它们。内容可能如下所示

<php

namespace apps\demo\v1\config {

    use shani\advisors\Configuration;
    use shani\engine\http\App;

    final class DevSettings extends Configuration
    {
        public function __construct(App &$app, array &$configurations)
        {
            parent::__construct($app, $configurations);
        }
        //Add all unimplemented methods here
	}
}

1.0.2.1 别名

假设我们的应用程序通过 https://:8008 提供，我们还想通过 http://127.0.0.1:8008、http://example.local 或更多...提供我们的应用程序。

这就是别名概念的出现，当应用程序通过多个主机名提供时。就像我们创建了 localhost.yml 文件一样，我们将创建 127.0.0.1.alias 文件和 example.local.alias 文件。

注意 文件 localhost.yml 必须在创建 .alias 文件之前可用，否则您的服务器会崩溃

127.0.0.1.alias 文件内容

localhost

example.local.alias 文件内容

localhost

正如我们所见，所有的.alias文件都必须包含它们指向的主机名。这就是在Shani应用程序中创建别名（们）的方法。

1.0.3 运行应用程序

再次假设我们的应用程序可以通过localhost:8008访问。我们网络服务器的默认端口是HTTP的8008和HTTPS的端口44380。我们可以使用以下URL来调用我们的world函数。

$ curl https://:8008/greetings/0/hello/0/world

恭喜！你已经完成了成为Shani开发者的第一步。

2.0 URL结构

Shani应用程序遵循以下URL模式

http://hostname[:port]/module-name/param1/resource-name/param2/function-name[/more-params][?query=q1]

分解上述模式，我们可以看到

module-name代表用户请求的当前资源模块。这是一个目录，其中包含该模块下的所有子资源。
param1和param2是资源标识符，可以是数字、字符串或其他任何东西
resource-name或有时称为controller-name是子资源。它是应用程序的实际实现，而
function-name是在资源类定义中可用的函数名。在函数名之后，您可以添加更多参数或附加查询字符串

示例

https://:8008/products/201/sales/10/details

Shani应用程序使用破折号到驼峰式转换将URL转换为有效的名称。

URL中的module-name代表项目结构中的module-name目录。
URL中的resource-name代表在module-name目录中的ResourceName类，以及视图目录中的resource-name目录
URL中的function-name代表在ResourceName类文件中的functionName，以及在视图目录中的function-name.php视图

其他URL部分保持不变。

贡献

欢迎提交拉取请求。对于重大更改，请先提出问题以讨论您想更改的内容。

请确保根据需要更新测试。

许可

GPL-3.0

godfreybwaira / shani

维护者

详细信息