Aimeos Laravel

aimeos/aimeos-laravel

제출자 Laravel Korea Discovery Bot

최신 v2026.10.2라이센스 MIT배포 2026년 11월 2일

결제·구독

클라우드 네이티브, API 우선 방식의 Laravel 이커머스 패키지로, AI를 통합해 초고속 온라인 쇼핑몰과 마켓플레이스, 복잡한 B2B 프로젝트를 구축할 수 있습니다

GitHub

Aimeos Laravel 이커머스 패키지

:star: GitHub에서 Star를 눌러 주세요. 큰 힘이 됩니다! 😀

Aimeos는 전문적이고 기능이 풍부하며 매우 빠른 Laravel 이커머스 패키지입니다. 기존 Laravel 애플리케이션에 5분 안에 설치할 수 있으며, 필요에 맞게 무엇이든 조정, 확장, 덮어쓰기, 커스터마이징할 수 있습니다.

주요 기능

Aimeos는 기능이 풍부한 이커머스 패키지입니다.

멀티 벤더, 멀티 채널, 멀티 웨어하우스
상품 1개부터 10억 개 이상까지
최대 20ms까지 단축되는 매우 빠른 속도
벤더 수에 제한이 없는 멀티 테넌트 이커머스 SaaS 솔루션 지원
번들, 바우처, 가상, 옵션 구성형, 맞춤형, 이벤트 상품
정기 결제를 지원하는 구독
100개 이상의 결제 게이트웨이
프론트엔드와 백엔드 모두 RTL(오른쪽에서 왼쪽) 완벽 지원
블록/구간별 가격 설정 기본 제공
고객/그룹 기반 가격 확장 기능
할인 및 바우처 지원
유연한 장바구니 규칙 시스템
기능이 풍부한 관리자 백엔드
보기 좋은 관리자 대시보드
설정 가능한 상품 데이터 세트
jsonapi.org 기반 JSON REST API
관리용 GraphQL API
완전한 모듈형 구조
높은 설정 자유도와 확장성
수백만 벤더를 수용하는 마켓플레이스 확장 기능
리치 스니펫을 포함한 완벽한 SEO 최적화
30개 이상의 언어로 번역
AI 기반 텍스트 번역
스마트폰과 태블릿에 최적화
안전하고 검증된 구현
고품질 소스 코드

... 그 밖의 Aimeos 기능도 확인해 보세요.

지원 언어:

데모를 확인해 보세요.

대안

완성형 쇼핑몰 애플리케이션

새 애플리케이션을 만들거나 Aimeos를 시험해 보고 싶다면 Aimeos 쇼핑몰 배포판(distribution)을 권장합니다. 빠른 시작에 필요한 모든 것이 들어 있어, 5분 안에 완전히 동작하는 온라인 쇼핑몰을 만들 수 있습니다.

:star: Aimeos 쇼핑몰 배포판

헤드리스 배포판

싱글 페이지 애플리케이션(SPA) 또는 프로그레시브 웹 애플리케이션(PWA)을 직접 만들 계획이고 Aimeos HTML 프론트엔드가 필요하지 않다면, Aimeos 헤드리스 배포판이 알맞은 선택입니다.

:star: Aimeos 헤드리스 배포판

지원 버전

현재 Aimeos Laravel 패키지는 2025.10 이상 버전을 완전히 지원합니다.

LTS 릴리스: 2026.10+ (Laravel 11.x, 12.x, 13.x)
이전 LTS 릴리스: 2025.10+ (Laravel 10.x, 11.x, 12.x)

메이저 버전 간 업그레이드가 필요하다면 업그레이드 가이드를 참고하세요.

요구 사항

Aimeos 쇼핑몰 배포판에는 다음 환경이 필요합니다.

Linux/Unix, WAMP/XAMP 또는 MacOS 환경
PHP >= 8.1
MySQL >= 5.7.8, MariaDB >= 10.2.2, PostgreSQL 9.6+, SQL Server 2019+
웹 서버(Apache, Nginx 또는 테스트용 내장 PHP 웹 서버)

필요한 PHP 확장이 없으면 composer가 누락된 의존성을 알려 줍니다.

메이저 버전 간 업그레이드가 필요하다면 업그레이드 가이드를 참고하세요.

데이터베이스

먼저 데이터베이스를 미리 생성하고, 애플리케이션 디렉터리의 .env 파일에 접속 설정을 추가해 두세요. 간혹 .env 파일 설정이 적용되지 않아 데이터베이스 연결 실패 예외가 발생하는 경우가 있습니다. 이럴 때는 ./config/shop.php 파일의 resource/db 섹션에도 데이터베이스 접속 정보를 추가하세요.

MySQL 5.7.8 또는 MariaDB 10.2.2 이상이 설치되어 있지 않다면 다음과 같은 오류가 발생할 수 있습니다.

Specified key was too long; max key length is 767 bytes

이 문제를 피하려면, 이미 생성된 새 테이블이 있다면 삭제한 뒤 ./config/database.php의 charset/collation 설정을 아래 값으로 바꾸고 Aimeos를 다시 설치하세요.

'connections' => [
    'mysql' => [
        // ...
        'charset' => 'utf8',
        'collation' => 'utf8_unicode_ci',
        // ...
    ]
]

주의: MySQL 서버가 기본으로 InnoDB 테이블을 생성하는지도 확인하세요. MyISAM 테이블은 동작하지 않으며 외래 키 제약 조건 오류가 발생합니다.

MySQL 이외의 데이터베이스 서버를 사용하려면 지원되는 데이터베이스 서버 문서에서 각 서버별 설정을 확인하세요. 지원하는 데이터베이스는 다음과 같습니다.

MySQL, MariaDB (완전 지원)
PostgreSQL (완전 지원)
SQL Server (완전 지원)

.env 파일에서 지원되는 데이터베이스 서버 중 하나를 사용하도록 설정했는지 확인하세요. 예:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=aimeos
DB_USERNAME=root
DB_PASSWORD=

주의: 기본으로 설정되어 있는 SQLite 데이터베이스는 지원되지 않습니다!

설치

Aimeos Laravel 온라인 쇼핑몰 패키지는 Composer 기반 라이브러리입니다. 기존 Laravel 애플리케이션의 루트 디렉터리에서 Composer 2.1+를 사용하면 가장 쉽게 설치할 수 있습니다.

wget https://getcomposer.org/download/latest-stable/composer.phar -O composer

그런 다음 Laravel 스켈레톤 애플리케이션의 composer.json에 아래 내용을 추가합니다.

    "prefer-stable": true,
    "minimum-stability": "dev",
    "require": {
        "aimeos/aimeos-laravel": "~2026.10",
        ...
    },
    "scripts": {
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force",
            "@php artisan vendor:publish --tag=public --ansi",
            "\\Aimeos\\Shop\\Composer::join"
        ],
        ...
    }

이어서 다음 명령으로 Aimeos 쇼핑몰 패키지를 설치합니다.

php composer update -W

마지막으로 아래 Artisan 명령을 실행하면 동작하는(또는 업데이트된) Aimeos 설치가 완료됩니다.

php artisan vendor:publish --tag=config --tag=publicphp artisan migratephp artisan aimeos:setup --option=setup/default/demo:1

운영 환경이거나 데모 데이터를 설치하고 싶지 않다면 --option=setup/default/demo:1 옵션을 빼고 실행하세요.

인증

Laravel 인증 스타터 키트 중 하나를 설정해야 합니다. Laravel Breeze가 가장 쉽지만 Jetstream을 사용할 수도 있습니다.

composer require laravel/breeze
php artisan breeze:install
npm install && npm run build # 앞선 명령에서 자동으로 실행되지 않은 경우

Laravel Breeze는 몇 가지 질문을 하는데, 가장 중요한 것은 사용할 스택의 종류입니다. "Blade"(가장 쉬운 방법)를 선택하고 나머지는 기본값을 사용하세요.

Breeze는 ./routes/web.php에 /profile 라우트도 추가하는데, 이 라우트가 aimeos_shop_account 라우트를 덮어쓸 수 있습니다. aimeos_shop_account 라우트가 없다는 예외를 피하려면 ./routes/web.php 파일의 아래 코드에서 URL을 /profile에서 /profile/me로 변경하세요.

Route::middleware('auth')->group(function () {
    Route::get('/profile/me', [ProfileController::class, 'edit'])->name('profile.edit');
    Route::patch('/profile/me', [ProfileController::class, 'update'])->name('profile.update');
    Route::delete('/profile/me', [ProfileController::class, 'destroy'])->name('profile.destroy');
});

자세한 내용은 Laravel 문서를 참고하세요.

인증 설정

마지막 단계로, App\Providers\AppServiceProvider 클래스의 boot() 메서드를 확장해 "admin" 권한을 어떻게 검사할지 app/Providers/AppServiceProvider.php에 정의합니다.

    public function boot()
    {
        // Keep the lines before

        \Illuminate\Support\Facades\Gate::define('admin', function($user, $class, $roles) {
            if( isset( $user->superuser ) && $user->superuser ) {
                return true;
            }
            return app( '\Aimeos\Shop\Base\Support' )->checkUserGroup( $user, $roles );
        });
    }

계정 생성

계속 진행하기 전에 인증 설정이 제대로 동작하는지 확인하세요. Aimeos 관리자 화면에 로그인할 수 있도록 Laravel 애플리케이션용 관리자 계정을 생성합니다.

php artisan aimeos:account --super <email>

이메일 주소가 로그인 사용자명이며, 이 계정은 프론트엔드에서도 사용할 수 있습니다. 새 계정을 보호하기 위해 명령이 비밀번호를 물어봅니다. --super(모든 항목에 접근 가능) 대신 --admin, --editor, --api를 사용하면 권한이 제한된 계정을 만들 수 있습니다.

MCP 브리지

Aimeos는 공식 Laravel MCP 서버를 통해 관리 도구를 제공할 수 있습니다. 이 전송 계층은 선택 사항이므로, MCP를 사용하지 않는 애플리케이션과 Laravel 10 애플리케이션은 SDK 없이도 계속 동작합니다. 지원되는 Laravel 버전에서는 애플리케이션에 다음 명령으로 설치합니다.

composer require laravel/mcp:^0.9

config/shop.php에서 엔드포인트를 활성화하고, 애플리케이션에서 사용하는 토큰 가드로 보호하세요. 아래 예시는 Laravel Sanctum을 사용합니다.

'guards' => [
    'mcp' => 'sanctum',
],
'routes' => [
    'mcp' => [
        'prefix' => 'admin/{site}/mcp',
        'middleware' => ['api', 'auth:sanctum'],
    ],
],

MCP 엔드포인트는 /admin/<site>/mcp에서 사용할 수 있습니다. 위의 라우트 설정과 laravel/mcp가 모두 갖춰지기 전까지는 비활성화 상태입니다. 이 서버는 관리용 읽기·쓰기 작업을 노출하므로, 인증 없이는 절대 활성화하지 마세요.

이 브리지는 서버를 시작하기 전에 Laravel의 일반적인 admin 게이트를 적용합니다. 또한 각 도구는 입력값을 검증하고, admin/mcp/resource 아래에 설정된 Aimeos 권한을 확인합니다. 슈퍼유저는 모든 도구에 접근할 수 있으며, 권한이 제한된 admin, editor, API 계정에는 리소스 권한을 명시적으로 지정해야 합니다.

설정

이미지를 올바르게 참조하려면 .env 파일에서 APP_URL을 실제 URL로 설정해야 합니다. 예:

APP_URL=http://127.0.0.1:8000

주의: .env 파일에서 Laravel이 file 세션 드라이버를 사용하는지 반드시 확인하세요. 그렇지 않으면 장바구니 내용이 올바르게 저장되지 않습니다!

SESSION_DRIVER=file

웹 서버가 ./public 디렉터리에 쓸 수 없다면 다음 디렉터리를 직접 만들어야 합니다.

mkdir public/aimeos public/vendor
chmod 777 public/aimeos public/vendor

운영 환경에서는 부여하는 권한을 더 구체적으로 제한하는 것이 좋습니다!

테스트

이제 브라우저에서 카탈로그 목록 페이지를 열 수 있습니다. 빠르게 시작하려면 내장 웹 서버를 사용하면 됩니다. 애플리케이션의 루트 디렉터리에서 다음 명령을 실행하세요.

php artisan serve

프론트엔드

브라우저에서 아래 주소로 쇼핑몰 목록 페이지에 접속합니다.

http://127.0.0.1:8000/shop/search

참고: Aimeos 패키지를 연동하면 /shop, /admin 같은 라우트가 Laravel 설치에 추가되지만 홈 페이지는 그대로 유지됩니다! 홈 페이지에도 Aimeos를 적용하려면 ./routes/web.php의 "/" 라우트를 아래 코드로 교체하세요.

Route::group(['middleware' => ['web']], function () {
    Route::get('/', '\Aimeos\Shop\Controller\CatalogController@homeAction')->name('aimeos_home');
});

멀티 벤더 구성이 필요하다면 여러 쇼핑몰 운영 문서를 읽어 보세요.

이렇게 하면 홈 페이지에 Aimeos 카탈로그 홈 컴포넌트가 표시되어 다음과 같은 보기 좋은 쇼핑몰 홈 페이지를 얻게 됩니다.

백엔드

내장 PHP 웹 서버(php artisan serve)가 계속 실행 중이라면 브라우저에서 아래 URL을 여세요.

http://127.0.0.1:8000/admin

새로 만든 사용자의 이메일 주소와 비밀번호를 입력하고 "Login"을 누릅니다. 관리자 화면으로 이동하지 않는다면(Laravel 문서에 따라 만든 인증 코드에 따라 다릅니다), 브라우저에서 /admin URL로 다시 접속하세요.

주의: 관리자가 아닌 사용자로 이미 로그인되어 있지 않은지 확인하세요! 이 경우 Laravel이 먼저 로그아웃을 요구하기 때문에 로그인이 동작하지 않습니다.

참고 사항

개발을 편하게 하려면 콘텐츠 캐시를 사용하지 않도록 설정하는 것이 좋습니다. Laravel 애플리케이션의 config/shop.php 파일 맨 아래에 다음 코드를 추가하면 됩니다.

    'madmin' => [
        'cache' => [
            'manager' => [
                'name' => 'None',
            ],
        ],
    ],

라이선스

Aimeos Laravel 패키지는 MIT 라이선스로 배포되며 무료로 사용할 수 있습니다.