包简介

Progressive Web App built with Laravel & Vue

README 文档

README

Progressive Web App built with Laravel & Vue

A Laravel package that seamlessly integrates Vue 3, Vue Router, and Pinia to build Progressive Web Applications with dynamic component loading and SPA-like experiences.

Features

🚀 Vue 3 Integration - Modern reactive framework with Composition API support
🛣️ Vue Router - Client-side routing with hash or history mode
🗄️ Pinia State Management - Official Vue state management library
📦 Dynamic Component Loading - Load Vue components on-demand via AJAX
⚡ Code Minification - Automatic JS/CSS minification for optimal performance
🎨 Customizable - Extensive configuration options for plugins, directives, and middleware
🔄 Hot Module Injection - Dynamically inject CSS, JavaScript, and templates from Blade views

Requirements

PHP >= 8.2
Laravel >= 12.0
Composer

Installation

Install the package via Composer:

composer require mxent/pwax

The service provider is auto-discovered by Laravel. After installation, run:

php artisan pwax:install

This publishes config/pwax.php. Pass --views to also publish the bundled Blade views, and --force to overwrite existing files.

Configuration

Publish the configuration file manually if you prefer:

php artisan vendor:publish --tag=pwax-config

Key options in config/pwax.php:

return [
    'hash_route'   => false,            // hash (#/) vs history routing
    'home'         => 'index',          // fallback named route
    'route_prefix' => '__pwax__',       // internal asset prefix

    'blade' => [
        'content' => null, 'head' => null, 'foot' => null,
        'error' => null, 'loader' => null,
    ],

    'customization' => [
        'init_spinner_color' => '#0c83ff',
        'init_spinner_bg'    => '#f3f3f3',
    ],

    'styles'  => [],
    'scripts' => [
        'https://unpkg.com/vue@3.5.18/dist/vue.global.prod.js',
        'https://unpkg.com/vue-router@4.5.1/dist/vue-router.global.prod.js',
        'https://unpkg.com/pinia@3.0.3/dist/pinia.iife.prod.js',
    ],

    'plugins'    => [],
    'directives' => [],
    'middleware' => [],

    'cache' => [
        'asset_ttl' => 3600,            // .js/.css cache lifetime
    ],

    'manifest_path' => '/manifest.webmanifest',
    'manifest' => [                     // Web App Manifest fields
        'name'        => env('APP_NAME', 'Pwax App'),
        'short_name'  => env('APP_NAME', 'Pwax'),
        'start_url'   => '/',
        'display'     => 'standalone',
        'theme_color' => '#0c83ff',
        'icons'       => [/* { src, sizes, type } */],
    ],

    'service_worker' => [
        'enabled'       => false,       // turn on to register /service-worker.js
        'path'          => '/service-worker.js',
        'cache_name'    => 'pwax-cache-v1',
        'precache'      => ['/'],
        'network_first' => true,
    ],
];

Progressive Web App

Pwax serves a Web App Manifest at /manifest.webmanifest and a service worker at /service-worker.js. The bundled <head> partial already emits the <link rel="manifest"> and theme-color meta tags.

To enable the service worker, set service_worker.enabled = true in config/pwax.php. The worker template can be customised by publishing it:

php artisan vendor:publish --tag=pwax-service-worker

Publishing Views

Publish the view files to customize the layout:

php artisan vendor:publish --tag=pwax-views

This publishes views to resources/views/vendor/pwax/.

Usage

Creating a Vue Component

Create a Blade view that contains <template>, <script>, and <style> sections:

{{-- resources/views/hello.blade.php --}}
<template>
    <div class="hello">
        <h1>@{{ message }}</h1>
        <button @click="increment">Count: @{{ count }}</button>
    </div>
</template>

<script>
export default {
    data() {
        return {
            message: 'Hello from PWax!',
            count: 0
        }
    },
    methods: {
        increment() {
            this.count++
        }
    }
}
</script>

<style>
.hello {
    padding: 20px;
    text-align: center;
}
</style>

Rendering a Component

In your controller, use the vue() helper function:

use Illuminate\Http\Request;

class HomeController extends Controller
{
    public function index()
    {
        return vue('hello');
    }
    
    public function profile()
    {
        return vue('profile', [
            'user' => auth()->user()
        ]);
    }
}

Routing

Define your routes as usual in routes/web.php:

Route::get('/', [HomeController::class, 'index'])->name('index');
Route::get('/profile', [HomeController::class, 'profile'])->name('profile');
Route::get('/about', [HomeController::class, 'about'])->name('about');

Use the router() helper to generate Vue Router compatible paths:

<template>
    <nav>
        <RouterLink to="{{ router('index') }}">Home</RouterLink>
        <RouterLink to="{{ router('profile') }}">Profile</RouterLink>
        <RouterLink to="{{ router('about') }}">About</RouterLink>
    </nav>
</template>

<script>
export default {
    //
}
</script>

Dynamic Imports

Use the import() helper to dynamically import components:

<script>
export default {
    async mounted() {
        // Import a component
        const { default: MyComponent } = @import('components.my-component')
        
        // Import with variable assignment
        const MyModal = @import('MyModal from components.modal')
    }
}
</script>

Advanced Configuration

Custom Plugins

Register custom Vue plugins in config/pwax.php:

'plugins' => [
    [
        'name' => 'myPlugin',
        'init' => 'app.use(MyCustomPlugin, { option: "value" })'
    ]
],

Custom Directives

Add custom Vue directives:

'directives' => [
    [
        'name' => 'focus',
        'init' => 'app.directive("focus", { mounted(el) { el.focus() } })'
    ]
],

Middleware

Execute JavaScript before component loads:

'middleware' => [
    [
        'name' => 'auth',
        'init' => 'if (!user.isAuthenticated) { window.location = "/login" }'
    ]
],

Security Best Practices

⚠️ View Names: Only use trusted view names. The package validates view names to prevent path traversal attacks.
🔒 Config Values: Avoid adding user-supplied data directly to config arrays like plugins or directives.
🛡️ CSRF Protection: Ensure CSRF tokens are included in AJAX requests if modifying data.
📝 Input Validation: Always validate and sanitize user input in your components.

Testing

The test suite uses Orchestra Testbench:

composer test

Coverage report:

composer test-coverage

Changelog

See CHANGELOG.md for version history and updates.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

This package is open-sourced software licensed under the MIT license.

Credits

Support

For issues, questions, or feature requests, please open an issue on GitHub.

mxent/pwax 适用场景与选型建议

mxent/pwax 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 48 次下载、GitHub Stars 达 0，最近一次更新时间为 2025 年 07 月 31 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「laravel」「SPA」「vue」「vue-router」「pwa」「progressive-web-app」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 mxent/pwax 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 mxent/pwax 我们能提供哪些服务？

定制开发 / 二次开发

基于 mxent/pwax 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 mxent/pwax 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

awes-io/table-builder 46

A component that allows creating responsive HTML tables or lists from data object

cretueusebiu/laravel-nuxt 1.15k

A Laravel-Nuxt starter project template.

okami101/laravel-admin 38

Admin panel generator for Laravel 8 and based on Vuetify Admin, a separate SPA admin framework running on top of REST APIs.

bbn/appui-core 1

Appui DOM Interface

mpmg/laravue 0

Code generation for MPMG projects that use Laravel and VueJs tecnologies.

k3ssen/symfony-vuetified 15

Bundle for Symfony 4.4, 5+, 6+ applications with Vuetify

mxent/pwax

包简介

关键字：